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 application's 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 exist in the pods format that need to be precompiled.

private
_treeFor(name): Tree
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 JSHint 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 exist that need to be precompiled.

private
treeGenerator( ): Tree

Generates a tree for the specified path

Public Constructors

lib/models/addon.js:122

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:208

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:173

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:155

public final name: String

The name of this addon.

lib/models/addon.js:195

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:230

public final pkg: Object

The contents of the addon's package.json.

lib/models/addon.js:186

public final project: Project

The root project to which this addon belongs.

lib/models/addon.js:164

public final root: String

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

lib/models/addon.js:220

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:1278

public blueprintsPath( ): String

Returns the path for addon blueprints.

Return:

String

The path for blueprints

Example:

lib/models/addon.js:1576

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:640

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:1296

public config(env, baseConfig): Object

Augments the application's 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
      • 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:1653

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:1335

public dependencies( ): Object

Return:

Object

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

lib/models/addon.js:320

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:344

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:738

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:1410

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:705

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:1386

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:239

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:373

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:1345

public isEnabled( ): Boolean

Return:

Boolean

Whether or not this addon is enabled

lib/models/addon.js:1634

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:1263

public moduleName( ): String

Returns the module name for this addon.

Return:

String

module name

lib/models/addon.js:1559

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:1543

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:1468

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:1535

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:1454

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:1481

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:1592

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:1354

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:1520

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:552

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:794

public treeForAddon(tree): Tree

Returns a tree for this addon

Parameters:

Name Type Attribute Description
tree Tree

Return:

Tree

Addon file tree

Example:

treeForAddon() {
  let emberVersion = new VersionChecker(this.project).for('ember-source');
  let shouldUsePolyfill = emberVersion.lt('4.5.0-alpha.4');

  if (shouldUsePolyfill) {
    return this._super.treeForAddon.apply(this, arguments);
  }
}
lib/models/addon.js:782

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:888

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:758

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:868

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:825

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:770

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:856

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:844

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:484

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:682

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:961

private _shouldCompilePodTemplates( ): Boolean

Looks in the addon/ and addon/templates trees to determine if template files exist 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:618

private _treeFor(name): Tree

Parameters:

Name Type Attribute Description
name String

Return:

Tree
lib/models/addon.js:1113

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:922

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:1079

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:359

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:409

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:459

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:1157

private jshintAddonTree( ): Tree

Returns a tree with JSHint output for all addon JS.

Return:

Tree

Tree with JShint output (tests)

lib/models/addon.js:1223

private preprocessJs( ): Tree

Preprocesses a javascript tree.

Return:

Tree

Preprocessed javascript

lib/models/addon.js:1234

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:947

private shouldCompileTemplates( ): Boolean

Looks in the addon/ and addon/templates trees to determine if template files exist 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:517

private treeGenerator( ): Tree

Generates a tree for the specified path

Return:

Tree