The core addon interface provides the main methods for integrating with Ember CLI's build pipeline and performing Babel transpilation within Ember applications and addons.
Initializes the addon and validates Ember CLI version compatibility (called automatically by Ember CLI).
/**
* Initializes the addon and validates ember-cli version
* @throws Error if ember-cli version is < 2.13.0
*/
init(): void;This method is called automatically during addon initialization and ensures compatibility with the minimum required Ember CLI version.
Generates Babel options for either direct Babel usage or broccoli-babel-transpiler integration.
/**
* Generates Babel options for transpilation
* @param configOrType - Either 'babel', 'broccoli', or a config object
* @param _config - Optional config object when first param is string
* @returns Babel options object configured for Ember
*/
buildBabelOptions(configOrType: string | object, _config?: object): object;Usage Examples:
// For direct babel-core usage
let babelAddon = this.addons.find(addon => addon.name === 'ember-cli-babel');
let options = babelAddon.buildBabelOptions('babel', config);
require('@babel/core').transform('some code', options);
// For broccoli-babel-transpiler usage
let options = babelAddon.buildBabelOptions('broccoli', config);
let BabelTranspiler = require('broccoli-babel-transpiler');
let transpiled = new BabelTranspiler(inputTree, options);Transpiles a Broccoli tree using the addon's Babel configuration, useful for addon developers who need to transpile additional trees.
/**
* Transpiles a Broccoli tree using Babel
* @param inputTree - Broccoli tree to transpile
* @param _config - Optional configuration override
* @returns Transpiled Broccoli tree
*/
transpileTree(inputTree: BroccoliTree, _config?: object): BroccoliTree;Usage Examples:
// Transpile a custom tree in an addon
let babelAddon = this.addons.find(addon => addon.name === 'ember-cli-babel');
let customTree = this.treeGenerator(['vendor']);
let transpiledTree = babelAddon.transpileTree(customTree);Returns array of file extensions that will be processed by the transpiler.
/**
* Gets array of file extensions supported for transpilation
* @param config - Optional configuration object
* @returns Array of supported file extensions
*/
getSupportedExtensions(config?: object): string[];The returned extensions depend on configuration:
['js']['js', 'ts']config['ember-cli-babel'].extensionsUsage Examples:
let babelAddon = this.addons.find(addon => addon.name === 'ember-cli-babel');
let extensions = babelAddon.getSupportedExtensions();
// Returns: ['js'] or ['js', 'ts'] based on TypeScript configurationDetermines if a specific Babel plugin is required based on the current compilation targets.
/**
* Checks if a Babel plugin is required for current targets
* @param pluginName - Name of the Babel plugin to check
* @returns true if plugin is required, false otherwise
*/
isPluginRequired(pluginName: string): boolean;Uses @babel/helper-compilation-targets to determine necessity based on config/targets.js configuration.
Usage Examples:
let babelAddon = this.addons.find(addon => addon.name === 'ember-cli-babel');
if (babelAddon.isPluginRequired('transform-arrow-functions')) {
// Arrow functions need to be transpiled for current targets
console.log('Arrow functions will be transpiled');
}Determines whether ES6 modules should be compiled to AMD format based on Ember CLI version and configuration.
/**
* Checks if ES6 modules should be compiled to AMD
* @returns true if modules should be compiled, false otherwise
*/
shouldCompileModules(): boolean;Returns true for Ember CLI versions > 2.12.0 unless explicitly disabled via compileModules: false configuration.
Usage Examples:
let babelAddon = this.addons.find(addon => addon.name === 'ember-cli-babel');
if (babelAddon.shouldCompileModules()) {
// ES6 modules will be compiled to AMD
console.log('Modules will be transpiled to AMD format');
}Registers the addon as a JavaScript preprocessor in Ember CLI's build pipeline (called automatically by Ember CLI).
/**
* Registers the addon as a JS preprocessor
* @param type - Preprocessor type
* @param registry - Ember CLI preprocessor registry
*/
setupPreprocessorRegistry(type: string, registry: object): void;This method registers ember-cli-babel to handle JavaScript (and optionally TypeScript) file transpilation. It configures:
Generates the addon tree containing Babel runtime helpers when external helpers are enabled (called automatically by Ember CLI).
/**
* Generates addon tree with Babel helpers when needed
* @returns Broccoli tree containing Babel helpers, or undefined
*/
treeForAddon(): BroccoliTree | undefined;This method:
includeExternalHelpers is enabled and this is the root babel addonGenerates cache keys for Broccoli tree caching (called automatically by Ember CLI).
/**
* Generates cache key for tree caching
* @param treeType - Type of tree being cached ('addon', 'app', etc.)
* @returns Cache key string based on configuration and dependencies
*/
cacheKeyForTree(treeType: string): string;This method:
These methods are part of the internal API and typically not used directly by addon developers:
/**
* Gets configuration options from parent addon or app
* @returns Configuration object
*/
_getAddonOptions(): object;/**
* Gets application-level configuration options
* @returns App configuration object
*/
_getAppOptions(): object;/**
* Gets compilation targets for babel-preset-env
* @returns Targets configuration object
*/
_getTargets(): object;/**
* Gets the version of @babel/runtime for helper plugin configuration
* @returns Version string or null if not available
*/
_getHelperVersion(): string | null;/**
* Generates the babel-plugin-transform-runtime configuration for external helpers
* @returns Array containing transform-runtime plugin configuration
*/
_getHelpersPlugin(): BabelPlugin[];/**
* Creates debug tree wrapper for broccoli debugging
* @returns Debug callback function for tree debugging
*/
_debugTree(): Function;The addon throws errors in the following cases:
ember-cli-babel@7 (used by {parent} at {path}) cannot be used by ember-cli versions older than 2.13, you used {version}useBabelConfig: true is set but no babel.config.js is found
Missing babel config file in the project root. Please double check if the babel config file exists or turn off the useBabelConfig option in your ember-cli-build.js file.includeExternalHelpers is configured at addon level instead of app level
includeExternalHelpers is not supported in addon configurations, it is an app-wide configuration optionWarning Messages:
The addon may issue warning messages in these scenarios:
{addonName} attempted to include external babel helpers to make your build size smaller, but your root app's ember-cli-babel version is not high enough. Please update ember-cli-babel to v7.3.0-beta.1 or later.