The plugin generation API allows external consumers to generate Ember-specific Babel plugins for use in custom babel.config.js configurations, enabling advanced build customization outside of the standard Ember CLI build pipeline.
The main export function that generates a complete array of Ember-specific Babel plugins.
/**
* Generates complete set of Ember-specific Babel plugins
* @param appRoot - Root directory path of the project (usually __dirname)
* @param config - Optional configuration object to customize plugin behavior
* @returns Array of Babel plugins required for Ember applications
*/
function buildEmberPlugins(appRoot: string, config?: PluginConfig): BabelPlugin[];
interface PluginConfig {
/** Disable module resolution plugins */
disableModuleResolution?: boolean;
/** Force enable EmberData packages polyfill */
emberDataVersionRequiresPackagesPolyfill?: boolean;
/** Ignore jQuery in modules API polyfill */
shouldIgnoreJQuery?: boolean;
/** Ignore @ember/string in modules API polyfill */
shouldIgnoreEmberString?: boolean;
/** Disable decorator and class property plugins */
shouldIgnoreDecoratorAndClassPlugins?: boolean;
/** Disable Ember modules API polyfill */
disableEmberModulesAPIPolyfill?: boolean;
}
type BabelPlugin = string | [string, any] | [any, any];Usage Examples:
// babel.config.js - Basic usage
const { buildEmberPlugins } = require('ember-cli-babel');
module.exports = function(api) {
api.cache(true);
return {
presets: [
[require.resolve('@babel/preset-env'), {
targets: require('./config/targets')
}]
],
plugins: [
// Include all Ember-specific plugins
...buildEmberPlugins(__dirname),
// Add custom plugins
require.resolve('babel-plugin-transform-object-rest-spread')
]
};
};
// babel.config.js - With custom configuration
const { buildEmberPlugins } = require('ember-cli-babel');
module.exports = function(api) {
api.cache(true);
return {
presets: [
[require.resolve('@babel/preset-env'), {
targets: require('./config/targets')
}]
],
plugins: [
// External helpers for smaller bundles
[require.resolve('@babel/plugin-transform-runtime'), {
version: require('@babel/runtime/package').version,
regenerator: false,
useESModules: true
}],
// Ember plugins with custom config
...buildEmberPlugins(__dirname, {
disableModuleResolution: false,
shouldIgnoreJQuery: true,
disableEmberModulesAPIPolyfill: false
})
]
};
};Individual functions for generating specific plugin categories, useful for fine-grained control.
/**
* Generates debug macro plugins for @ember/debug stripping
* @param appRoot - Root directory path of the project
* @returns Array of debug macro Babel plugins
*/
function getDebugMacroPlugins(appRoot: string): BabelPlugin[];Generates plugins for:
@ember/debug statement stripping in production@ember/application/deprecations handling@glimmer/env DEBUG flag processingUsage Example:
const { getDebugMacroPlugins } = require('ember-cli-babel');
// Use only debug macro plugins
const plugins = getDebugMacroPlugins(__dirname);/**
* Generates Ember modules API polyfill plugin
* @param appRoot - Root directory path of the project
* @param config - Configuration object
* @returns Array containing modules API polyfill plugin or empty array
*/
function getEmberModulesAPIPolyfill(appRoot: string, config: object): BabelPlugin[] | [];Provides polyfill for legacy Ember global API access patterns when using modern Ember versions.
Usage Example:
const { getEmberModulesAPIPolyfill } = require('ember-cli-babel');
const plugins = getEmberModulesAPIPolyfill(__dirname, {
disableEmberModulesAPIPolyfill: false
});/**
* Generates EmberData packages polyfill plugin
* @param appRoot - Root directory path of the project
* @param config - Configuration object
* @returns Array containing EmberData polyfill plugin or empty array
*/
function getEmberDataPackagesPolyfill(appRoot: string, config: object): BabelPlugin[] | [];Provides polyfill for EmberData package structure changes in older versions.
Usage Example:
const { getEmberDataPackagesPolyfill } = require('ember-cli-babel');
const plugins = getEmberDataPackagesPolyfill(__dirname, {
emberDataVersionRequiresPackagesPolyfill: true
});/**
* Generates module resolution plugins for AMD compilation
* @param config - Configuration object
* @returns Array of module resolution plugins or empty array
*/
function getModuleResolutionPlugins(config: object): BabelPlugin[] | [];Provides plugins for:
Usage Example:
const { getModuleResolutionPlugins } = require('ember-cli-babel');
const plugins = getModuleResolutionPlugins({
disableModuleResolution: false
});/**
* Generates decorator and class property plugins
* @param config - Configuration object
* @returns Array of decorator and class plugins or empty array
*/
function getProposalDecoratorsAndClassPlugins(config: object): BabelPlugin[] | [];Provides plugins for:
Usage Example:
const { getProposalDecoratorsAndClassPlugins } = require('ember-cli-babel');
const plugins = getProposalDecoratorsAndClassPlugins({
shouldIgnoreDecoratorAndClassPlugins: false
});The generated plugins are organized into functional categories:
Disables AMD module compilation and path resolution plugins.
buildEmberPlugins(__dirname, {
disableModuleResolution: true
});Forces inclusion of EmberData packages polyfill regardless of version detection.
buildEmberPlugins(__dirname, {
emberDataVersionRequiresPackagesPolyfill: true
});Excludes jQuery from modules API polyfill ignore list.
buildEmberPlugins(__dirname, {
shouldIgnoreJQuery: true
});Excludes @ember/string from modules API polyfill ignore list.
buildEmberPlugins(__dirname, {
shouldIgnoreEmberString: true
});Disables all decorator and class feature plugins.
buildEmberPlugins(__dirname, {
shouldIgnoreDecoratorAndClassPlugins: true
});Disables the Ember modules API polyfill entirely.
buildEmberPlugins(__dirname, {
disableEmberModulesAPIPolyfill: true
});The plugin generation system automatically detects package versions to determine which polyfills and transforms are necessary:
This ensures optimal plugin configuration for your specific dependency versions.
Plugin generation is designed to be robust: