{"id":15015727,"url":"https://github.com/emberjs/ember-cli-babel","last_synced_at":"2025-11-17T04:01:11.169Z","repository":{"id":24685264,"uuid":"28096281","full_name":"emberjs/ember-cli-babel","owner":"emberjs","description":"Ember CLI plugin for Babel","archived":false,"fork":false,"pushed_at":"2024-05-24T03:20:42.000Z","size":2737,"stargazers_count":153,"open_issues_count":50,"forks_count":120,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-10-29T15:44:47.557Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emberjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"emberjs","open_collective":"emberjs"}},"created_at":"2014-12-16T16:44:30.000Z","updated_at":"2023-12-19T17:37:22.000Z","dependencies_parsed_at":"2023-10-15T07:26:12.652Z","dependency_job_id":"e46c81b9-6ca9-4689-93de-488e67831aeb","html_url":"https://github.com/emberjs/ember-cli-babel","commit_stats":{"total_commits":719,"total_committers":80,"mean_commits":8.9875,"dds":0.5924895688456189,"last_synced_commit":"dff2a54370dd92d7f9b3fe3fcb9b02f344eebbaa"},"previous_names":["6to5/ember-cli-6to5","emberjs/ember-cli-babel","babel/ember-cli-babel"],"tags_count":153,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-cli-babel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-cli-babel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-cli-babel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emberjs%2Fember-cli-babel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emberjs","download_url":"https://codeload.github.com/emberjs/ember-cli-babel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415967,"owners_count":20935387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:47:50.889Z","updated_at":"2025-11-17T04:01:06.144Z","avatar_url":"https://github.com/emberjs.png","language":"JavaScript","funding_links":["https://github.com/sponsors/emberjs","https://opencollective.com/emberjs"],"categories":[],"sub_categories":[],"readme":"# ember-cli-babel\n\n[![CI Status](https://github.com/babel/ember-cli-babel/workflows/CI/badge.svg)](https://github.com/babel/ember-cli-babel/actions?query=workflow%3ACI+branch%3Amaster)\n\nThis Ember-CLI plugin uses [Babel](https://babeljs.io/) and\n[@babel/preset-env](https://babeljs.io/docs/en/next/babel-preset-env.html) to\nallow you to use latest Javascript in your Ember CLI project.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Compatibility](#compatibility)\n- [Usage](#usage)\n  * [Options](#options)\n    + [External Helpers](#external-helpers)\n    + [Enabling Source Maps](#enabling-source-maps)\n    + [Modules](#modules)\n    + [Disabling Debug Tooling Support](#disabling-debug-tooling-support)\n    + [Enabling TypeScript Transpilation](#enabling-typescript-transpilation)\n  * [Babel config file usage](#babel-config-usage)  \n  * [Addon usage](#addon-usage)\n    + [Adding Custom Plugins](#adding-custom-plugins)\n    + [Additional Trees](#additional-trees)\n    + [`buildBabelOptions` usage](#buildbabeloptions-usage)\n    + [`getSupportedExtensions` usage](#getsupportedextensions-usage)\n    + [`transpileTree` usage](#transpiletree-usage)\n  * [Debug Tooling](#debug-tooling)\n    + [Debug Macros](#debug-macros)\n    + [General Purpose Env Flags](#general-purpose-env-flags)\n    + [Parallel Builds](#parallel-builds)\n\n## Installation\n\n```\nember install ember-cli-babel\n```\n\n## Compatibility\n\n- ember-cli-babel 7.x requires ember-cli 2.13 or above\n\n## Usage\n\nThis plugin should work without any configuration after installing. By default\nit will take every `.js` file in your project and run it through the Babel\ntranspiler to convert your ES6 code to code supported by your target browsers\n(as specified in `config/targets.js` in ember-cli \u003e= 2.13). Running non-ES6\ncode through the transpiler shouldn't change the code at all (likely just a\nformat change if it does).\n\nIf you need to customize the way that `babel-preset-env` configures the plugins\nthat transform your code, you can do it by passing in any of the\n[babel/babel-preset-env options](https://babeljs.io/docs/en/next/babel-preset-env.html#options).\n*Note: `.babelrc` files are ignored by default.*\n\nExample (configuring babel directly):\n\n```js\n// ember-cli-build.js\n\nlet app = new EmberApp({\n  babel: {\n    // enable \"loose\" mode\n    loose: true,\n    // don't transpile generator functions\n    exclude: [\n      'transform-regenerator',\n    ],\n    plugins: [\n      require.resolve('transform-object-rest-spread')\n    ]\n  }\n});\n```\n\nExample (configuring ember-cli-babel itself):\n\n```js\n// ember-cli-build.js\n\nlet app = new EmberApp({\n  'ember-cli-babel': {\n    compileModules: false\n  }\n});\n```\n\n### Options\n\nThere are a few different options that may be provided to ember-cli-babel.\nThese options are typically set in an apps `ember-cli-build.js` file, or in an\naddon or engine's `index.js`.\n\n```ts\ntype BabelPlugin = string | [string, any] | [any, any];\n\ninterface EmberCLIBabelConfig {\n  /**\n    Configuration options for babel-preset-env.\n    See https://github.com/babel/babel-preset-env/tree/v1.6.1#options for details on these options.\n  */\n  babel?: {\n    spec?: boolean;\n    loose?: boolean;\n    debug?: boolean;\n    include?: string[];\n    exclude?: string[];\n    useBuiltIns?: boolean;\n    sourceMaps?: boolean | \"inline\" | \"both\";\n    plugins?: BabelPlugin[];\n  };\n\n  /**\n    Configuration options for ember-cli-babel itself.\n  */\n  'ember-cli-babel'?: {\n    includeExternalHelpers?: boolean;\n    compileModules?: boolean;\n    disableDebugTooling?: boolean;\n    disablePresetEnv?: boolean;\n    disableEmberModulesAPIPolyfill?: boolean;\n    disableEmberDataPackagesPolyfill?: boolean;\n    disableDecoratorTransforms?: boolean;\n    enableTypeScriptTransform?: boolean;\n    extensions?: string[];\n  };\n}\n```\n\nThe exact location you specify these options varies depending on the type of\nproject you're working on. As a concrete example, to add\n`babel-plugin-transform-object-rest-spread` so that your project can use object\nrest/spread syntax, you would do something like this in an app:\n\n```js\n// ember-cli-build.js\nlet app = new EmberApp(defaults, {\n  babel: {\n    plugins: [require.resolve('transform-object-rest-spread')]\n  }\n});\n```\n\nIn an engine:\n```js\n// index.js\nmodule.exports = EngineAddon.extend({\n  babel: {\n    plugins: [require.resolve('transform-object-rest-spread')]\n  }\n});\n```\n\nIn an addon:\n```js\n// index.js\nmodule.exports = {\n  options: {\n    babel: {\n      plugins: [require.resolve('transform-object-rest-spread')]\n    }\n  }\n};\n```\n\n#### External Helpers\n\nBabel often includes helper functions to handle some of the more complex logic\nin codemods. These functions are inlined by default, so they are duplicated in\nevery file that they are used in, which adds some extra weight to final builds.\n\nEnabling `includeExternalHelpers` will cause Babel to import these helpers from\na shared module, reducing app size overall. This option is available _only_ to\nthe root application, because it is a global configuration value due to the fact\nthat there can only be one version of helpers included.\n\nNote that there is currently no way to allow or ignore helpers, so all\nhelpers will be included, even ones which are not used. If your app is small,\nthis could add to overall build size, so be sure to check.\n\n`ember-cli-babel` will attempt to include helpers if it believes that it will\nlower your build size, using a number of heuristics. You can override this to\nforce inclusion or exclusion of helpers in your app by passing `true` or `false`\nto `includeExternalHelpers` in your `ember-cli-babel` options.\n\n```js\n// ember-cli-build.js\n\nlet app = new EmberApp(defaults, {\n  'ember-cli-babel': {\n    includeExternalHelpers: true\n  }\n});\n```\n\n#### Enabling Source Maps\n\nBabel generated source maps will enable you to debug your original ES6 source\ncode. This is disabled by default because it will slow down compilation times.\n\nTo enable it, pass `sourceMaps: 'inline'` in your `babel` options.\n\n```js\n// ember-cli-build.js\n\nlet app = new EmberApp(defaults, {\n  babel: {\n    sourceMaps: 'inline'\n  }\n});\n```\n\n#### Modules\n\nOlder versions of Ember CLI (`\u003c 2.12`) use its own ES6 module transpiler.\nBecause of that, this plugin disables Babel module compilation by ignoring\nthat transform when running under affected ember-cli versions. If you find that\nyou want to use the Babel module transform instead of the Ember CLI one, you'll\nhave to explicitly set `compileModules` to `true` in your configuration. If\n`compileModules` is anything other than `true`, this plugin will leave the\nmodule syntax compilation up to Ember CLI.\n\n#### Disabling Debug Tooling Support\n\nIf for some reason you need to disable this debug tooling, you can opt-out via\nconfiguration.\n\nIn an app that would look like:\n\n```js\n// ember-cli-build.js\nmodule.exports = function(defaults) {\n  let app = new EmberApp(defaults, {\n    'ember-cli-babel': {\n      disableDebugTooling: true\n    }\n  });\n\n  return app.toTree();\n}\n```\n\n#### Enabling TypeScript Transpilation\n\nBabel needs a transform plugin in order to transpile TypeScript. When you\ninstall `ember-cli-typescript \u003e= 4.0`, this plugin is automatically enabled.\n\nIf you don't want to install `ember-cli-typescript`, you can still enable\nthe TypeScript-Babel transform. You will need to set `enableTypeScriptTransform`\nto `true` in select file(s).\n\n\n\u003cdetails\u003e\n\u003csummary\u003eApps\u003c/summary\u003e\n\n```js\n/* ember-cli-build.js */\n\nconst EmberApp = require('ember-cli/lib/broccoli/ember-app');\n\nmodule.exports = function (defaults) {\n  const app = new EmberApp(defaults, {\n    // Add options here\n    'ember-cli-babel': {\n      enableTypeScriptTransform: true,\n    },\n  });\n\n  return app.toTree();\n};\n```\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eAddons\u003c/summary\u003e\n\n```js\n/* ember-cli-build.js */\n\nconst EmberAddon = require('ember-cli/lib/broccoli/ember-addon');\n\nmodule.exports = function (defaults) {\n  const app = new EmberAddon(defaults, {\n    // Add options here\n    'ember-cli-babel': {\n      enableTypeScriptTransform: true,\n    },\n  });\n\n  return app.toTree();\n};\n```\n\n```js\n/* index.js */\n\nmodule.exports = {\n  name: require('./package').name,\n\n  options: {\n    'ember-cli-babel': {\n      enableTypeScriptTransform: true,\n    },\n  },\n};\n```\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eEngines\u003c/summary\u003e\n\n```js\n/* ember-cli-build.js */\n\nconst EmberAddon = require('ember-cli/lib/broccoli/ember-addon');\n\nmodule.exports = function (defaults) {\n  const app = new EmberAddon(defaults, {\n    // Add options here\n    'ember-cli-babel': {\n      enableTypeScriptTransform: true,\n    },\n  });\n\n  return app.toTree();\n};\n```\n\n```js\n/* index.js */\n\nconst { buildEngine } = require('ember-engines/lib/engine-addon');\n\nmodule.exports = buildEngine({\n  name: require('./package').name,\n\n  'ember-cli-babel': {\n    enableTypeScriptTransform: true,\n  },\n});\n```\n\n\u003c/details\u003e\n\n\nNOTE: Setting `enableTypeScriptTransform` to `true` does *not* enable\ntype-checking. For integrated type-checking, you will need\n[`ember-cli-typescript`](https://ember-cli-typescript.com).\n\n### Babel config usage\n\nIf you want to use the existing babel config from your project instead of the auto-generated one from this addon, then you would need to *opt-in* by passing the config `useBabelConfig: true` as a child property of `ember-cli-babel` in your `ember-cli-build.js` file.\n\n*Note: If you are using this option, then you have to make sure that you are adding all of the required plugins required for Ember to transpile correctly.*\n\nExample usage:\n\n```js\n//ember-cli-build.js\n\nlet app = new EmberAddon(defaults, {\n  \"ember-cli-babel\": {\n    useBabelConfig: true,\n    // ember-cli-babel related options\n  },\n});\n```\n\n```js\n//babel.config.js\n\nconst { buildEmberPlugins } = require(\"ember-cli-babel\");\n\nmodule.exports = function (api) {\n  api.cache(true);\n\n  return {\n    presets: [\n      [\n        require.resolve(\"@babel/preset-env\"),\n        {\n          targets: require(\"./config/targets\"),\n        },\n      ],\n    ],\n    plugins: [\n      // if you want external helpers\n      [\n        require.resolve(\"@babel/plugin-transform-runtime\"),\n        {\n          version: require(\"@babel/plugin-transform-runtime/package\").version,\n          regenerator: false,\n          useESModules: true,\n        },\n      ],\n      // this is where all the ember required plugins would reside\n      ...buildEmberPlugins(__dirname, { /*customOptions if you want to pass in */ }),\n    ],\n  };\n};\n```\n\n#### Ember Plugins\n\nEmber Plugins is a helper function that returns a list of plugins that are required for transpiling Ember correctly. You can import this helper function and add it to your existing `babel.config` file.\nThe first argument is **required** which is the path to the root of your project (generally `__dirname`).\n**Config options:**\n\n```js\n{\n  disableModuleResolution: boolean, // determines if you want the module resolution enabled\n  emberDataVersionRequiresPackagesPolyfill: boolean, // enable ember data's polyfill\n  shouldIgnoreJQuery: boolean, // ignore jQuery\n  shouldIgnoreEmberString: boolean, // ignore ember string\n  shouldIgnoreDecoratorAndClassPlugins: boolean, // disable decorator plugins\n  disableEmberModulesAPIPolyfill: boolean, // disable ember modules API polyfill\n}\n```\n### Addon usage (for V1 Addons)\n\n#### Note for V2 Addons (Embroider Compatibility)\n\nV2 Addons do not use `ember-cli-babel` and hence should remove `ember-cli-babel` from their dependencies entirely.\n\nYou can read up on how each of the V1 features described below can be re-expressed within a V2 addon via the links below:\n\n- [V2 Addon Format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format/)\n- [Migrating an Ember addon to the next-gen v2 format](https://www.kaliber5.de/en/blog/v2-addon_en)\n\n#### Adding Custom Plugins\n\nYou can add custom plugins to be used during transpilation of the `addon/` or\n`addon-test-support/` trees by ensuring that your addon's `options.babel` is\nproperly populated (as mentioned above in the `Options` section).\n\n#### Additional Trees\n\nFor addons which want additional customizations, they are able to interact with\nthis addon directly.\n\n```ts\ninterface EmberCLIBabel {\n  /**\n    Used to generate the options that will ultimately be passed to babel itself.\n  */\n  buildBabelOptions(type: 'babel' | 'broccoli', config?: EmberCLIBabelConfig): Opaque;\n\n  /**\n    Supports easier transpilation of non-standard input paths (e.g. to transpile\n    a non-addon NPM dependency) while still leveraging the logic within\n    ember-cli-babel for transpiling (e.g. targets, preset-env config, etc).\n  */\n  transpileTree(inputTree: BroccoliTree, config?: EmberCLIBabelConfig): BroccoliTree;\n\n  /**\n    Used to determine if a given plugin is required by the current target configuration.\n    Does not take `includes` / `excludes` into account.\n\n    See https://github.com/babel/babel-preset-env/blob/master/data/plugins.json for the list\n    of known plugins.\n  */\n  isPluginRequired(pluginName: string): boolean;\n}\n```\n\n#### `buildBabelOptions` usage\n\n```js\n// find your babel addon (can use `this.findAddonByName('ember-cli-babel')` in ember-cli@2.14 and newer)\nlet babelAddon = this.addons.find(addon =\u003e addon.name === 'ember-cli-babel');\n\n// create the babel options to use elsewhere based on the config above\nlet options = babelAddon.buildBabelOptions('babel', config)\n\n// now you can pass these options off to babel or broccoli-babel-transpiler\nrequire('babel-core').transform('something', options);\n```\n\n#### `getSupportedExtensions` usage\n\n```js\n// find your babel addon (can use `this.findAddonByName('ember-cli-babel')` in ember-cli@2.14 and newer)\nlet babelAddon = this.addons.find(addon =\u003e addon.name === 'ember-cli-babel');\n\n// create the babel options to use elsewhere based on the config above\nlet extensions = babelAddon.getSupportedExtensions(config)\n```\n\n#### `transpileTree` usage\n\n```js\n// find your babel addon (can use `this.findAddonByName('ember-cli-babel')` in ember-cli@2.14 and newer)\nlet babelAddon = this.addons.find(addon =\u003e addon.name === 'ember-cli-babel');\n\n// invoke .transpileTree passing in the custom input tree\nlet transpiledCustomTree = babelAddon.transpileTree(someCustomTree);\n```\n\n### Debug Tooling\n\nIn order to allow apps and addons to easily provide good development mode\nergonomics (assertions, deprecations, etc) but still perform well in production\nmode ember-cli-babel automatically manages stripping / removing certain debug\nstatements. This concept was originally proposed in [ember-cli/rfcs#50](https://github.com/ember-cli/rfcs/pull/50),\nbut has been slightly modified during implementation (after researching what works well and what does not).\n\n#### Debug Macros\n\nTo add convienient deprecations and assertions, consumers (in either an app or an addon) can do the following:\n\n```js\nimport { deprecate, assert } from '@ember/debug';\n\nexport default Ember.Component.extend({\n  init() {\n    this._super(...arguments);\n    deprecate(\n      'Passing a string value or the `sauce` parameter is deprecated, please pass an instance of Sauce instead',\n      false,\n      { until: '1.0.0', id: 'some-addon-sauce' }\n    );\n    assert('You must provide sauce for x-awesome.', this.sauce);\n  }\n})\n```\n\nIn testing and development environments those statements will be executed (and\nassert or deprecate as appropriate), but in production builds they will be\ninert (and stripped during minification).\n\nThe following are named exports that are available from `@ember/debug`:\n\n* `function deprecate(message: string, predicate: boolean, options: any): void` - Results in calling `Ember.deprecate`.\n* `function assert(message: string, predicate: boolean): void` - Results in calling `Ember.assert`.\n* `function warn(message: string, predicate: boolean): void` - Results in calling `Ember.warn`.\n\n#### General Purpose Env Flags\n\nIn some cases you may have the need to do things in debug builds that isn't\nrelated to asserts/deprecations/etc. For example, you may expose certain API's\nfor debugging only. You can do that via the `DEBUG` environment flag:\n\n```js\nimport { DEBUG } from '@glimmer/env';\n\nconst Component = Ember.Component.extend();\n\nif (DEBUG) {\n  Component.reopen({\n    specialMethodForDebugging() {\n      // do things ;)\n    }\n  });\n}\n```\n\nIn testing and development environments `DEBUG` will be replaced by the boolean\nliteral `true`, and in production builds it will be replaced by `false`. When\nran through a minifier (with dead code elimination) the entire section will be\nstripped.\n\nPlease note, that these general purpose environment related flags (e.g. `DEBUG`\nas a boolean flag) are imported from `@glimmer/env` not from an `@ember`\nnamespace.\n\n#### Parallel Builds\n\nBy default, [broccoli-babel-transpiler] will attempt to spin up several\nsub-processes (~1 per available core), to achieve parallelization. (Once Node.js\nhas built-in worker support, we plan to utilize it.) This yields significant Babel\nbuild time improvements.\n\nUnfortunately, some Babel plugins may break this functionality.\nWhen this occurs, we gracefully fallback to the old serial strategy.\n\nTo have the build fail when failing to do parallel builds, opt-in is via:\n\n```js\nlet app = new EmberAddon(defaults, {\n  'ember-cli-babel': {\n    throwUnlessParallelizable: true\n  }\n});\n```\nor via environment variable via\n```sh\nTHROW_UNLESS_PARALLELIZABLE=1 ember serve\n```\n\nThe `ember-cli-build` option is only specifying that *your* `ember-cli-babel` is parallelizable, not that all of them are.\n\nThe environment variable works by instructing **all** `ember-cli-babel` instances to put themselves in parallelize mode (or throw).\n\n*Note: Future versions will enable this flag by default.*\n\nRead more about [broccoli parallel transpilation].\n\n[broccoli-babel-transpiler]: https://github.com/babel/broccoli-babel-transpiler\n[broccoli parallel transpilation]: https://github.com/babel/broccoli-babel-transpiler#parallel-transpilation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femberjs%2Fember-cli-babel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femberjs%2Fember-cli-babel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femberjs%2Fember-cli-babel/lists"}