Extends:

CoreObject → Addon

Root class for an Addon. If your addon module exports an Object this will be extended from this base class. If you export a constructor (function), it will not extend from this class.

Hooks:

Constructor Summary

Public Constructors
public
Addon(parent, project)

Root class for an Addon. If your addon module exports an Object this will be extended from this base class. If you export a constructor (function), it will not extend from this class.

Property Summary

Public Properties
public final

The set of addons that this addon itself depends on.

public final

The host app instance.

public final

The name of this addon.

public final

This addon's parent.

public final

The contents of the addon's package.json.

public final

The root project to which this addon belongs.

public final

The absolute path of the root directory where this addon is located.

public final
ui: UI

A console-ui object that can be used to log messages for the user and indicate progress on long-running operations.

Method Summary

Public Methods
public

Returns the path for addon blueprints.

public
buildError(error)

This hook is called when an error occurs during the preBuild, postBuild or outputReady hooks for addons, or when the build fails

public
cacheKeyForTree(treeType): String

Calculates a cacheKey for the given treeType. It is expected to return a cache key allowing multiple builds of the same tree to simply return the original tree (preventing duplicate work). If it returns null / undefined the tree in question will opt out of this caching system.

public
config(env, baseConfig): Object

Augments the applications configuration settings.

public
contentFor(type, config, content)

Allow addons to implement contentFor method to add string output into the associated {{content-for 'foo'}} section in index.html

public
public

Find an addon of the current addon.

public

Check if the current addon intends to be hinted. Typically this is for hinting/linting libraries such as eslint or jshint

public
import(asset, [options])

Imports an asset into this addon.

public

Allows addons to define a custom transform function that other addons and app can use when using app.import.

public
included(parent)

This method is called when the addon is included in a build. You would typically use this hook to perform additional imports

public

Allows the specification of custom addon commands. Expects you to return an object whose key is the name of the command and value is the command instance..

public
init(parent, project)

Initializes the addon. If you override this method make sure and call this._super.init && this._super.init.apply(this, arguments); or your addon will not work.

public

Allows to mark the addon as developing, triggering live-reload in the project the addon is linked to.

public
public
lintTree(treeType, tree)

Return value is merged into the tests tree. This lets you inject linter output as test results.

public

Returns the module name for this addon.

public
outputReady(result)

This hook is called after the build has been processed and the build files have been copied to the output directory

public
postBuild(result)

This hook is called after a build is complete.

public
postprocessTree(type, tree): Tree

Post-process a tree

public
preBuild(result)

This hook is called before a build takes place.

public
preprocessTree(type, tree): Tree

Pre-process a tree

public
serverMiddleware(startOptions)

This hook allows you to make changes to the express server run by ember-cli.

public
setupPreprocessorRegistry(type, registry)

Used to add preprocessors to the preprocessor registry. This is often used by addons like ember-cli-htmlbars and ember-cli-coffeescript to add a template or js preprocessor to the registry.

public

Can be used to exclude addons from being added as a child addon.

public

This hook allows you to make changes to the express server run by testem.

public
treeFor(name): Tree

Returns a given type of tree (if present), merged with the application tree. For each of the trees available using this method, you can also use a direct method called treeFor[Type] (eg. treeForApp).

public
treeForAddon(tree): Tree

Returns a tree for this addon

public
treeForAddonTemplates(tree): Tree

Returns the tree for this addon's templates

public

Returns the tree for all test files namespaced to a given addon.

public
treeForApp(tree): Tree

Returns the tree for all app files

public
treeForPublic(tree): Tree

Returns the tree for all public files

public
treeForStyles(tree): Tree

Returns the tree for all style files

public
treeForTemplates(tree): Tree

Returns the tree for all template files

public
treeForTestSupport(tree): Tree

Returns the tree for all test support files

public
treeForVendor(tree): Tree

Returns the tree for all vendor files

Private Methods
private
_eachProjectAddonInvoke(methodName, args)

Invoke the specified method for each of the project's addons.

private

This method climbs up the hierarchy of addons up to the host application.

private

Looks in the addon/ and addon/templates trees to determine if template files exists in the pods format that need to be precompiled.

private
_treeFor(name): Tree
private
_warn( )
private
addonJsFiles( ): Tree

Returns a tree containing the addon's js files

private
compileAddon(tree): Tree

Runs the addon tree through preprocessors.

private
compileStyles(addonStylesTree): Tree

Runs the styles tree through preprocessors.

private
compileTemplates(tree): Tree

Runs the templates tree through preprocessors.

private
concatFiles(tree, options): Tree

Shorthand method for broccoli-concat

private

Discovers all child addons of this addon and an AddonInfo about each addon in this.addonPackages (keyed on addon name).

private
eachAddonInvoke(methodName, args)

Invoke the specified method for each enabled addon.

private
jshintAddonTree( ): Tree

Returns a tree with JSHhint output for all addon JS.

private
preprocessJs( ): Tree

Preprocesses a javascript tree.

private

Returns a tree with all javascript for this addon.

private

Looks in the addon/ and addon/templates trees to determine if template files exists that need to be precompiled.

private
treeGenerator( ): Tree

Generates a tree for the specified path

Public Constructors

lib/models/addon.js:137

public Addon(parent, project)

Parameters:

Name Type Attribute Description
parent Project | Addon

The project or addon that directly depends on this addon

project Project

The current project (deprecated)

Public Properties

lib/models/addon.js:223

public final addons: Addon[]

The set of addons that this addon itself depends on.

This array is populated from the addon's listed dependencies and any items in ember-addon.paths in its package.json.

lib/models/addon.js:188

public final app: EmberApp

The host app instance.

Note: this property will only be present on addons that are a direct dependency of the application itself, not of other addons. It is also not available in init(), but will be set before setupPreprocessorRegistry() and included() are invoked.

lib/models/addon.js:170

public final name: String

The name of this addon.

lib/models/addon.js:210

public final parent: Project | Addon

This addon's parent.

If the addon is a direct dependency of an application, then parent will be the corresponding project instance. If it's a dependency of another addon, then parent will be a reference to that addon.

lib/models/addon.js:245

public final pkg: Object

The contents of the addon's package.json.

lib/models/addon.js:201

public final project: Project

The root project to which this addon belongs.

lib/models/addon.js:179

public final root: String

The absolute path of the root directory where this addon is located.

lib/models/addon.js:235

public final ui: UI

A console-ui object that can be used to log messages for the user and indicate progress on long-running operations.

Public Methods

lib/models/addon.js:1347

public blueprintsPath( ): String

Returns the path for addon blueprints.

Return:

String

The path for blueprints

Example:

lib/models/addon.js:1646

public buildError(error)

This hook is called when an error occurs during the preBuild, postBuild or outputReady hooks for addons, or when the build fails

Uses:

  • Custom error handling during build process

Parameters:

Name Type Attribute Description
error Error

The error that was caught during the processes listed above

Example:

lib/models/addon.js:674

public cacheKeyForTree(treeType): String

Calculates a cacheKey for the given treeType. It is expected to return a cache key allowing multiple builds of the same tree to simply return the original tree (preventing duplicate work). If it returns null / undefined the tree in question will opt out of this caching system.

This method is invoked prior to calling treeFor with the same tree name.

You should override this method if you implement custom treeFor or treeFor* methods, which cause addons to opt-out of this caching.

Parameters:

Name Type Attribute Description
treeType String

Return:

String

cacheKey

lib/models/addon.js:1365

public config(env, baseConfig): Object

Augments the applications configuration settings.

Object returned from this hook is merged with the application's configuration object.

Application's configuration always take precedence.

Uses:

  • Modifying configuration options (see list of defaults here)
    • For example
      • minifyJS
      • storeConfigInMeta
      • et, al

Parameters:

Name Type Attribute Description
env String

Name of current environment (ie "development")

baseConfig Object

Initial application configuration

Return:

Object

Configuration object to be merged with application configuration.

Example:

config(environment, appConfig) {
  return {
    someAddonDefault: "foo"
  };
}
lib/models/addon.js:1723

public contentFor(type, config, content)

Allow addons to implement contentFor method to add string output into the associated {{content-for 'foo'}} section in index.html

Uses:

  • For instance, to inject analytics code into index.html

Parameters:

Name Type Attribute Description
type Object
config Object
content Object

Example:

lib/models/addon.js:1405

public dependencies( ): Object

Return:

Object

The addon's dependencies based on the addon's package.json

lib/models/addon.js:343

public findOwnAddonByName( )

Find an addon of the current addon.

Example: ember-data depends on ember-cli-babel and wishes to have additional control over transpilation this method helps.

// ember-data/index.js
treeForAddon(tree) {
  let babel = this.findOwnAddonByName('ember-cli-babel');

  return babel.transpileTree(tree, {
    // customize the babel step (see: ember-cli-addons readme for more details);
  });
}
lib/models/addon.js:367

public hintingEnabled( )

Check if the current addon intends to be hinted. Typically this is for hinting/linting libraries such as eslint or jshint

lib/models/addon.js:772

public import(asset, [options])

Imports an asset into this addon.

Parameters:

Name Type Attribute Description
asset Object | String

Either a path to the asset or an object with environment names and paths as key-value pairs.

options Object
  • optional

Options object

options.type String
  • optional

Either 'vendor' or 'test', defaults to 'vendor'

options.prepend Boolean
  • optional

Whether or not this asset should be prepended, defaults to false

options.destDir String
  • optional

Destination directory, defaults to the name of the directory the asset is in

lib/models/addon.js:1480

public importTransforms( ): Object

Allows addons to define a custom transform function that other addons and app can use when using app.import.

This function is not implemented by default

Uses:

  • An app or addons want to transform a dependency that is being imported using app.import.

Return:

Object

An object with custom transforms

Example:

importTransforms() {
  return {
    'my-custom-transform': function(tree, options) {
      // transform the incoming tree and return the updated tree
    }
  };
}

Alternatively, if you want to process options before being passed into the custom transform function, use:

importTransforms() {
  return {
    'my-custom-transform': {
      transform: function(tree, options) {
          // transform the incoming tree and return the updated tree
      },
      processOptions: function(assetPath, entry, options) {
        // process your options

        return options
      }
  };
}
lib/models/addon.js:739

public included(parent)

This method is called when the addon is included in a build. You would typically use this hook to perform additional imports

Uses:

  • including vendor files
  • setting configuration options

Note: Any options set in the consuming application will override the addon.

Parameters:

Name Type Attribute Description
parent EmberApp | EmberAddon

The parent object which included this addon

Example:

included(parent) {
  this._super.included.apply(this, arguments);
  this.import(somePath);
}
lib/models/addon.js:1456

public includedCommands( ): Object

Allows the specification of custom addon commands. Expects you to return an object whose key is the name of the command and value is the command instance..

This function is not implemented by default

Uses:

  • Include custom commands into consuming application

Return:

Object

An object with included commands

Example:

includedCommands() {
  return {
    'do-foo': require('./lib/commands/foo')
  };
}
lib/models/addon.js:254

public init(parent, project)

Initializes the addon. If you override this method make sure and call this._super.init && this._super.init.apply(this, arguments); or your addon will not work.

Parameters:

Name Type Attribute Description
parent Project | Addon

The project or addon that directly depends on this addon

project Project

The current project (deprecated)

Example:

init(parent, project) {
  this._super.init && this._super.init.apply(this, arguments);
  this._someCustomSetup();
}
lib/models/addon.js:396

public isDevelopingAddon( ): Boolean

Allows to mark the addon as developing, triggering live-reload in the project the addon is linked to.

Uses:

  • Working on projects with internal addons

Return:

lib/models/addon.js:1415

public isEnabled( ): Boolean

Return:

Boolean

Whether or not this addon is enabled

lib/models/addon.js:1704

public lintTree(treeType, tree)

Return value is merged into the tests tree. This lets you inject linter output as test results.

Uses:

  • JSHint
  • any other form of automated test generation that turns code into tests

Parameters:

Name Type Attribute Description
treeType String

app, tests, templates, or addon

tree Tree

tree of files (JavaScript files for app, tests, and addon types)

Example:

lib/models/addon.js:1332

public moduleName( ): String

Returns the module name for this addon.

Return:

String

module name

lib/models/addon.js:1629

public outputReady(result)

This hook is called after the build has been processed and the build files have been copied to the output directory

It's passed a result object which contains:

  • directory Path to build output

Parameters:

Name Type Attribute Description
result Object

Build result object

Example:

  • Opportunity to symlink or copy files elsewhere.
  • ember-cli-rails-addon
    • In this case we are using this in tandem with a rails middleware to remove a lock file. This allows our ruby gem to block incoming requests until after the build happens reliably.
lib/models/addon.js:1613

public postBuild(result)

This hook is called after a build is complete.

It's passed a result object which contains:

  • directory Path to build output

Uses:

  • Slow tree listing
  • May be used to manipulate your project after build has happened

Parameters:

Name Type Attribute Description
result Object

Build result object

lib/models/addon.js:1538

public postprocessTree(type, tree): Tree

Post-process a tree

Parameters:

Name Type Attribute Description
type String

What kind of tree (eg. 'js', 'css', 'template')

tree Tree

Tree to process

Return:

Tree

Processed tree

Example:

lib/models/addon.js:1605

public preBuild(result)

This hook is called before a build takes place.

Parameters:

Name Type Attribute Description
result Object

Build object

lib/models/addon.js:1524

public preprocessTree(type, tree): Tree

Pre-process a tree

Uses:

  • removing / adding files from the build.

Parameters:

Name Type Attribute Description
type String

What kind of tree (eg. 'js', 'css', 'template')

tree Tree

Tree to process

Return:

Tree

Processed tree

lib/models/addon.js:1551

public serverMiddleware(startOptions)

This hook allows you to make changes to the express server run by ember-cli.

It's passed a startOptions object which contains:

  • app Express server instance
  • options A hash with:
    • project Current project
    • watcher
    • environment

This function is not implemented by default

Uses:

  • Tacking on headers to each request
  • Modifying the request object

Note: that this should only be used in development, and if you need the same behavior in production you'll need to configure your server.

Parameters:

Name Type Attribute Description
startOptions Object

Express server start options

Example:

serverMiddleware(startOptions) {
  var app = startOptions.app;

  app.use(function(req, res, next) {
    // Some middleware
  });
}
lib/models/addon.js:1662

public setupPreprocessorRegistry(type, registry)

Used to add preprocessors to the preprocessor registry. This is often used by addons like ember-cli-htmlbars and ember-cli-coffeescript to add a template or js preprocessor to the registry.

Uses:

  • Adding preprocessors to the registry.

Parameters:

Name Type Attribute Description
type String

either "self" or "parent"

registry Object

the registry to be set up

Example:

setupPreprocessorRegistry(type, registry) {
  // ensure that broccoli-ember-hbs-template-compiler is not processing hbs files
  registry.remove('template', 'broccoli-ember-hbs-template-compiler');

  registry.add('template', {
    name: 'ember-cli-htmlbars',
    ext: 'hbs',
    _addon: this,
    toTree(tree) {
      var htmlbarsOptions = this._addon.htmlbarsOptions();
      return htmlbarsCompile(tree, htmlbarsOptions);
    },

    precompile(string) {
      var htmlbarsOptions = this._addon.htmlbarsOptions();
      var templateCompiler = htmlbarsOptions.templateCompiler;
      return utils.template(templateCompiler, string);
    }
  });

  if (type === 'parent') {
    this.parentRegistry = registry;
  }
}
lib/models/addon.js:1424

public shouldIncludeChildAddon(childAddon): Boolean

Can be used to exclude addons from being added as a child addon.

Uses:

  • Abstract away multiple addons while only including one into the built assets

Parameters:

Name Type Attribute Description
childAddon Addon

Return:

Boolean

Whether or not a child addon is supposed to be included

Example:

shouldIncludeChildAddon(childAddon) {
  if(childAddon.name === 'ember-cli-some-legacy-select-component') {
    return this.options.legacyMode;
  } else if(childAddon.name === 'ember-cli-awesome-new-select-component') {
    return !this.options.legacyMode;
  } else {
    return this._super.shouldIncludeChildAddon.apply(this, arguments);
  }
}
lib/models/addon.js:1590

public testemMiddleware(app)

This hook allows you to make changes to the express server run by testem.

This function is not implemented by default

Uses:

  • Adding custom test-specific endpoints
  • Manipulating HTTP requests in tests

Parameters:

Name Type Attribute Description
app Object

the express app instance

lib/models/addon.js:586

public treeFor(name): Tree

Returns a given type of tree (if present), merged with the application tree. For each of the trees available using this method, you can also use a direct method called treeFor[Type] (eg. treeForApp).

Available tree names:

Uses:

  • manipulating trees at build time

Parameters:

Name Type Attribute Description
name String

Return:

Tree
lib/models/addon.js:828

public treeForAddon(tree): Tree

Returns a tree for this addon

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Addon file tree

Example:

treeForAddon() {
  var tree = this._super.treeForAddon.apply(this, arguments);
  var checker = new VersionChecker(this);
  var isOldEmber = checker.for('ember', 'bower').lt('1.13.0');

  if (isOldEmber) {
    tree = new Funnel(tree, { exclude: [ /instance-initializers/ ] });
  }

  return tree;
}
lib/models/addon.js:816

public treeForAddonTemplates(tree): Tree

Returns the tree for this addon's templates

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Addon Template file tree

lib/models/addon.js:925

public treeForAddonTestSupport(tree): Tree

Returns the tree for all test files namespaced to a given addon.

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree
lib/models/addon.js:792

public treeForApp(tree): Tree

Returns the tree for all app files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

App file tree

lib/models/addon.js:905

public treeForPublic(tree): Tree

Returns the tree for all public files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Public file tree

lib/models/addon.js:862

public treeForStyles(tree): Tree

Returns the tree for all style files

Parameters:

Name Type Attribute Description
tree Tree

The tree to process, usually app/styles/ in the addon.

Return:

Tree

The return tree has the same contents as the input tree, but is moved so that the app/styles/ path is preserved.

lib/models/addon.js:804

public treeForTemplates(tree): Tree

Returns the tree for all template files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Template file tree

lib/models/addon.js:893

public treeForTestSupport(tree): Tree

Returns the tree for all test support files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Test Support file tree

lib/models/addon.js:881

public treeForVendor(tree): Tree

Returns the tree for all vendor files

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Vendor file tree

Private Methods

lib/models/addon.js:506

private _eachProjectAddonInvoke(methodName, args)

Invoke the specified method for each of the project's addons.

Parameters:

Name Type Attribute Description
methodName String

the method to invoke on each addon

args Array

the arguments to pass to the invoked method

lib/models/addon.js:716

private _findHost( )

This method climbs up the hierarchy of addons up to the host application.

This prevents previous addons (prior to this.import, ca 2.7.0) to break at importing assets when they are used nested in other addons.

lib/models/addon.js:998

private _shouldCompilePodTemplates( ): Boolean

Looks in the addon/ and addon/templates trees to determine if template files exists in the pods format that need to be precompiled.

This is executed once when building, but not on rebuilds.

Return:

Boolean

indicates if pod based templates need to be compiled for this addon

lib/models/addon.js:652

private _treeFor(name): Tree

Parameters:

Name Type Attribute Description
name String

Return:

Tree
lib/models/addon.js:574

private _warn( )

lib/models/addon.js:1269

private addonJsFiles( ): Tree

Deprecated: This method is deprecated.

Returns a tree containing the addon's js files

Return:

Tree

The filtered addon js files

lib/models/addon.js:1149

private compileAddon(tree): Tree

Runs the addon tree through preprocessors.

Parameters:

Name Type Attribute Description
tree Tree

Addon file tree

Return:

Tree

Compiled addon tree

lib/models/addon.js:960

private compileStyles(addonStylesTree): Tree

Runs the styles tree through preprocessors.

Parameters:

Name Type Attribute Description
addonStylesTree Tree

Styles file tree

Return:

Tree

Compiled styles tree

lib/models/addon.js:1116

private compileTemplates(tree): Tree

Runs the templates tree through preprocessors.

Parameters:

Name Type Attribute Description
tree Tree

Templates file tree

Return:

Tree

Compiled templates tree

lib/models/addon.js:382

private concatFiles(tree, options): Tree

Shorthand method for broccoli-concat

Parameters:

Name Type Attribute Description
tree Tree

Tree of files

options Object

Options for broccoli-concat

Return:

Tree

Modified tree

lib/models/addon.js:434

private discoverAddons( )

Discovers all child addons of this addon and an AddonInfo about each addon in this.addonPackages (keyed on addon name).

Child addons include those from 'dependencies' (not devDependencies) and in-repo addons

Any packageInfos that we find that are marked as not valid are excluded.

lib/models/addon.js:481

private eachAddonInvoke(methodName, args)

Invoke the specified method for each enabled addon.

Parameters:

Name Type Attribute Description
methodName String

the method to invoke on each addon

args Array

the arguments to pass to the invoked method

lib/models/addon.js:1203

private jshintAddonTree( ): Tree

Returns a tree with JSHhint output for all addon JS.

Return:

Tree

Tree with JShint output (tests)

lib/models/addon.js:1286

private preprocessJs( ): Tree

Preprocesses a javascript tree.

Return:

Tree

Preprocessed javascript

lib/models/addon.js:1297

private processedAddonJsFiles(the): Tree

Returns a tree with all javascript for this addon.

Parameters:

Name Type Attribute Description
the Tree

tree to preprocess

Return:

Tree

Processed javascript file tree

lib/models/addon.js:984

private shouldCompileTemplates( ): Boolean

Looks in the addon/ and addon/templates trees to determine if template files exists that need to be precompiled.

This is executed once when building, but not on rebuilds.

Return:

Boolean

indicates if templates need to be compiled for this addon

lib/models/addon.js:539

private treeGenerator( ): Tree

Generates a tree for the specified path

Return:

Tree