Babel Plugin: Ember Modules API Polyfill

3.5.0 · active · verified Wed Apr 22

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.

Common errors

```
TypeError: Invalid option 'blacklist' passed to 'babel-plugin-ember-modules-api-polyfill'
```
cause Using the deprecated `blacklist` configuration option with plugin versions 3.0.0 or later.

fix Change the `blacklist` option to `ignore` in your `babel-plugin-ember-modules-api-polyfill` configuration.
```
TypeError: Cannot read properties of undefined (reading 'container')
```
cause A bug affecting certain code coverage configurations when using plugin versions prior to 3.2.2.

fix Upgrade `babel-plugin-ember-modules-api-polyfill` to version `3.2.2` or newer to resolve this bug.
```
Syntax Error: Decorators must be applied to an identifier, not an alias.
```
cause Incorrect transpilation of aliased decorator identifiers within decorated methods in plugin versions prior to 3.2.1.

fix Upgrade `babel-plugin-ember-modules-api-polyfill` to version `3.2.1` or newer to correctly handle aliased decorators.

Warnings

breaking 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.
Fix: Update your Babel configuration to replace `blacklist` with `ignore` for this plugin's options.
gotcha 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.
Fix: Add `{ useEmberModule: true }` as an option to the plugin configuration in your Babel setup.
gotcha 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.
Fix: Upgrade `ember-cli-babel` to `^6.6.0` or a newer compatible version in your `package.json`.

Install

npm install babel-plugin-ember-modules-api-polyfill npm
yarn add babel-plugin-ember-modules-api-polyfill yarn
pnpm add babel-plugin-ember-modules-api-polyfill pnpm

Imports

babel-plugin-ember-modules-api-polyfill
wrong:
```
module.exports = { plugins: ['ember-modules-api-polyfill'] };
```
correct:
```
module.exports = { plugins: ['babel-plugin-ember-modules-api-polyfill'] };
```
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.
babel-plugin-ember-modules-api-polyfill (with options)
wrong:
```
module.exports = { plugins: ['babel-plugin-ember-modules-api-polyfill', { useEmberModule: true }] };
```
correct:
```
module.exports = { plugins: [['babel-plugin-ember-modules-api-polyfill', { useEmberModule: true }]] };
```
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.

Quickstart

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.

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-ember-modules-api-polyfill', {
      // Recommended option for Ember 3.27+ to avoid global window.Ember deprecation
      useEmberModule: true
    }]
  ]
};

// src/my-component.js (Example input code)
import Component from '@ember/component';
import { inject as service } from '@ember/service';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';

export default class MyComponent extends Component {
  @service auth;
  @tracked count = 0;

  @action
  increment() {
    this.count++;
    console.log(`Current count: ${this.count}`);
  }

  constructor() {
    super(...arguments);
    console.log('Auth service injected:', this.auth);
  }
}

// To apply the transformation with Babel CLI (assuming babel-cli is installed):
// npx babel src/my-component.js --out-file dist/my-component.js --config-file babel.config.js
// The output in dist/my-component.js would contain code using Ember.Component, Ember.inject.service, etc.

view raw JSON →