{"id":16299,"library":"babel-plugin-ember-modules-api-polyfill","title":"Babel Plugin: Ember Modules API Polyfill","description":"babel-plugin-ember-modules-api-polyfill is a Babel plugin designed to facilitate the adoption of the modern JavaScript Modules API (RFC #176) by Ember addon authors. It achieves this by transpiling new module import statements (e.g., `import { inject } from \"@ember/service\"`) back into their equivalent legacy global object references (e.g., `const inject = Ember.inject.service`) during the build process. This mechanism ensures that addons can leverage contemporary Ember API patterns without sacrificing compatibility with older Ember applications that have not yet fully migrated. Currently at version 3.5.0, the plugin maintains an active release cadence, frequently incorporating bug fixes and enhancements, often driven by updates to the underlying `ember-rfc176-data` package and evolving Ember API requirements. Its primary role is to provide a smooth transition path for Ember applications from a global object dependency model to a more modularized architecture.","status":"active","version":"3.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli/babel-plugin-ember-modules-api-polyfill","tags":["javascript","babel-plugin"],"install":[{"cmd":"npm install babel-plugin-ember-modules-api-polyfill","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-ember-modules-api-polyfill","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-ember-modules-api-polyfill","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Ember CLI to detect and apply this plugin in its build pipeline; ensures proper integration and functionality.","package":"ember-cli-babel","optional":false}],"imports":[{"note":"This plugin is configured by its string name in Babel configurations (e.g., `.babelrc`, `babel.config.js`). Omission of the `babel-plugin-` prefix is a common configuration mistake.","wrong":"module.exports = { plugins: ['ember-modules-api-polyfill'] };","symbol":"babel-plugin-ember-modules-api-polyfill","correct":"module.exports = { plugins: ['babel-plugin-ember-modules-api-polyfill'] };"},{"note":"When passing options to a Babel plugin, the plugin name string and its options object must be nested within an additional array. Failing to do so will result in Babel misinterpreting the configuration.","wrong":"module.exports = { plugins: ['babel-plugin-ember-modules-api-polyfill', { useEmberModule: true }] };","symbol":"babel-plugin-ember-modules-api-polyfill (with options)","correct":"module.exports = { plugins: [['babel-plugin-ember-modules-api-polyfill', { useEmberModule: true }]] };"}],"quickstart":{"code":"// babel.config.js\nmodule.exports = {\n  plugins: [\n    ['babel-plugin-ember-modules-api-polyfill', {\n      // Recommended option for Ember 3.27+ to avoid global window.Ember deprecation\n      useEmberModule: true\n    }]\n  ]\n};\n\n// src/my-component.js (Example input code)\nimport Component from '@ember/component';\nimport { inject as service } from '@ember/service';\nimport { action } from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nexport default class MyComponent extends Component {\n  @service auth;\n  @tracked count = 0;\n\n  @action\n  increment() {\n    this.count++;\n    console.log(`Current count: ${this.count}`);\n  }\n\n  constructor() {\n    super(...arguments);\n    console.log('Auth service injected:', this.auth);\n  }\n}\n\n// To apply the transformation with Babel CLI (assuming babel-cli is installed):\n// npx babel src/my-component.js --out-file dist/my-component.js --config-file babel.config.js\n// The output in dist/my-component.js would contain code using Ember.Component, Ember.inject.service, etc.","lang":"javascript","description":"This quickstart demonstrates how to configure `babel-plugin-ember-modules-api-polyfill` in a `babel.config.js` file and provides an example Ember component utilizing modern module imports that the plugin will transpile to legacy global API access."},"warnings":[{"fix":"Update your Babel configuration to replace `blacklist` with `ignore` for this plugin's options.","message":"The plugin's configuration option `blacklist` was renamed to `ignore` in v3.0.0. Using `blacklist` in versions 3.0.0 or newer will cause configuration errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Add `{ useEmberModule: true }` as an option to the plugin configuration in your Babel setup.","message":"For Ember 3.27+ applications, it is highly recommended to enable the `useEmberModule` option in the plugin's configuration to mitigate `window.Ember` deprecation warnings.","severity":"gotcha","affected_versions":">=3.3.0"},{"fix":"Upgrade `ember-cli-babel` to `^6.6.0` or a newer compatible version in your `package.json`.","message":"This plugin is designed to operate within the Ember CLI build system via `ember-cli-babel`. Ensure your project's `ember-cli-babel` dependency is version `6.6.0` or higher to guarantee proper integration and expected behavior.","severity":"gotcha","affected_versions":"N/A (check `ember-cli-babel` version)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change the `blacklist` option to `ignore` in your `babel-plugin-ember-modules-api-polyfill` configuration.","cause":"Using the deprecated `blacklist` configuration option with plugin versions 3.0.0 or later.","error":"TypeError: Invalid option 'blacklist' passed to 'babel-plugin-ember-modules-api-polyfill'"},{"fix":"Upgrade `babel-plugin-ember-modules-api-polyfill` to version `3.2.2` or newer to resolve this bug.","cause":"A bug affecting certain code coverage configurations when using plugin versions prior to 3.2.2.","error":"TypeError: Cannot read properties of undefined (reading 'container')"},{"fix":"Upgrade `babel-plugin-ember-modules-api-polyfill` to version `3.2.1` or newer to correctly handle aliased decorators.","cause":"Incorrect transpilation of aliased decorator identifiers within decorated methods in plugin versions prior to 3.2.1.","error":"Syntax Error: Decorators must be applied to an identifier, not an alias."}],"ecosystem":"npm"}