Skip to content

Latest commit

 

History

History
398 lines (251 loc) · 10.6 KB

ADDON_HOOKS.md

File metadata and controls

398 lines (251 loc) · 10.6 KB
Raw

Table of Contents:

  1. config

For each hook we'll cover the following (if applicable):

  • Received arguments
  • Source
  • Default implementation
  • Uses
  • Examples

Compendium is largely based of a talk by @rwjblue which can be found here

Config

Augments the applications configuration settings. Object returned from this hook is merged with the application's configuration object. Application's configuration always take precedence.

Received arguments:

  • env - name of current environment (ie "developement")
  • baseConfig - Initial application config

Source: lib/models/addon.js:312

Default implementation:

Addon.prototype.config = function (env, baseConfig) {
  var configPath = path.join(this.root, 'config', 'environment.js');

  if (fs.existsSync(configPath)) {
    var configGenerator = require(configPath);

    return configGenerator(env, baseConfig);
  }
};

Uses:

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

Examples:

blueprintsPath

Tells the application where your blueprints exist.

Received arguments: None

Source: lib/models/addon.js:304

Default implementation:

Addon.prototype.blueprintsPath = function() {
  var blueprintPath = path.join(this.root, 'blueprints');

  if (fs.existsSync(blueprintPath)) {
    return blueprintPath;
  }
};

Uses:

  • Let application know where blueprints exists.

Examples:

includedCommands

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.

Received arguments: None

Source: lib/models/project.js:234

Default implementation: None

Uses:

  • Include custom commands into consuming application

Examples:

  // https://github.com/rwjblue/ember-cli-divshot/blob/v0.1.6/index.js
  includedCommands: function() {
    return {
      'divshot': require('./lib/commands/divshot')
    };
  }

serverMiddleware

Designed to manipulate requests in development mode.

Received arguments:

  • options (eg express_instance, project, watcher, environment)

Source: lib/tasks/server/express-server.js:63

Default implementation: None

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.

Examples:

postBuild

Gives access to the result of the tree, and the location of the output.

Received arguments:

  • Result object from broccoli build
    • result.directory - final output path

Source: lib/models/builder.js:111

Default implementation: None

Uses:

  • Slow tree listing
  • May be used to manipulate your project after build has happened
  • Opportunity to symlink or copy files elsewhere.

Examples:

  • 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.

preBuild

Hook called before build takes place.

Received arguments:

Source: lib/models/builder.js:114

Default implementation: None

Uses:

Examples:

  • ember-cli-rails-addon
    • In this case we are using this in tandem with a rails middleware to create a lock file. [See postBuild]

buildError

buildError hook will be called on when an error occurs during the preBuild or postBuild hooks for addons, or when builder#build fails

Received arguments:

  • The error that was caught during the processes listed above

Source: lib/models/builder.js:122

Default implementation: None

Uses:

  • Custom error handling during build process

Examples:

included

Usually used to import assets into the application.

Received arguments:

Source: lib/broccoi/ember-app.js:216

Default implementation: None

Uses:

  • including vendor files
  • setting configuration options

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

Examples:

// https://github.com/yapplabs/ember-colpick/blob/master/index.js
included: function colpick_included(app) {
  this._super.included(app);

  var colpickPath = path.join(app.bowerDirectory, 'colpick');

  this.app.import(path.join(colpickPath, 'js',  'colpick.js'));
  this.app.import(path.join(colpickPath, 'css', 'colpick.css'));
}

postprocessTree

Received arguments:

  • post processing type (eg all)
  • receives tree after build

Source: lib/broccoli/ember-app.js:251

Default implementation: None

Uses:

  • fingerprint assets
  • running processes after build but before toTree

Examples:

lintTree

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

Received arguments:

  • tree type ('app', 'tests', or 'addon')
  • tree of Javascript files

Source: lib/broccoli/ember-app.js:326

Default implementation: None

Uses:

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

Examples:

contentFor

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

Received arguments:

  • type
  • config

Source: lib/broccoli/ember-app.js:953

Default implementation: None

Uses:

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

Examples:

treeFor

Return value is merged with application tree of same type

Received arguments:

  • returns given type of tree (eg app, vendor, bower)

Source: lib/broccoli/ember-app.js:240

Default implementation:

Addon.prototype.treeFor = function treeFor(name) {
  this._requireBuildPackages();

  var tree;
  var trees = [];

  if (tree = this._treeFor(name)) {
    trees.push(tree);
  }

  if (this.isDevelopingAddon() && this.app.hinting && name === 'app') {
    trees.push(this.jshintAddonTree());
  }

  return this.mergeTrees(trees.filter(Boolean));
};

Uses:

  • manipulating trees at build time

Examples:

treeFor (cont...)

Instead of overriding treeFor and acting only if the tree you receive matches the one you need EmberCLI has custom hooks for the following Broccoli trees

  • treeForApp
  • treeForStyles
  • treeForTemplates
  • treeForAddon
  • treeForVendor
  • treeForTestSupport
  • treeForPublic

isDevelopingAddon

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

Received arguments: None

Default implementation: None

Uses:

  • Working on projects with internal addons

Examples:

  // addon index.js
  isDevelopingAddon: function() {
    return true;
  }

See more here