Generators & Blueprints


Ember CLI ships with “Blueprints”, snippet generators for many of the entities - models, controllers, components, and so on - that you’ll need in your app. Blueprints allow us to share common Ember patterns in the community and you can even define your own.

To see a list of all available blueprints, with a short description of what they do, run ember generate --help or ember g --help, for short, at any time. For a longer, more detailed description of each blueprint, look in the appendix to this guide.

Generating Blueprints

This in an example of how to generate a Route Blueprint.

ember generate route foo

  create app/routes/foo.js
  create app/templates/foo.hbs
  create tests/unit/routes/foo-test.js

For a list of all available blueprints, run:

ember help generate

Defining a Custom Blueprint

You can define your own blueprints using ember generate blueprint <name>:

ember generate blueprint foo

  create blueprints/.jshintrc
  create blueprints/foo/files/.gitkeep
  create blueprints/foo/index.js

Blueprints in your project’s directory take precedence over those packaged with ember-cli. This makes it easy to override the built-in blueprints just by generating one with the same name.


You can generate certain built-in blueprints with a pods structure by passing the --pod option.

ember generate route foo --pod

  create app/foo/route.js
  create app/foo/template.hbs
  create tests/unit/foo/route-test.js

If you have podModulePrefix defined in your environment, your generated pod path will be automatically prefixed with it.

// podModulePrefix: app/pods
ember generate route foo --pod

  create app/pods/foo/route.js
  create app/pods/foo/template.hbs
  create tests/unit/pods/foo/route-test.js

The built-in blueprints that support pods structure are:

  • adapter
  • component
  • controller
  • model
  • route
  • resource
  • serializer
  • template
  • transform
  • view

Blueprints that don’t support pods structure will simply ignore the --pod option and use the default structure.

If you would like to use the pods structure as the default for your project, you can set usePods in your .ember-cli config file to true (setting was previously named usePodsByDefault). To generate or destroy a blueprint in the classic type structure while usePods is true, use the --classic flag.

With the usePods set to true.

// .ember-cli
    "usePods": true

The following would occur when generating a route:

ember generate route taco

  create app/taco/route.js
  create app/taco/template.hbs
  create tests/unit/taco/route-test.js

ember generate route taco --classic

  create app/routes/taco.js
  create app/templates/taco.hbs
  create tests/unit/routes/taco-test.js

Blueprint Structure

Blueprints follow a simple structure. Let’s take the built-in helper blueprint as an example:

  ├── files
  │   ├── app
  │   │   └── helpers
  │   │       └── __name__.js
  └── index.js

The accompanying test is in another blueprint. Because it has the same name with a -test suffix, it is generated automatically with the helper blueprint in this case.

  ├── files
  │   └── tests
  │       └── unit
  │           └── helpers
  │               └── __name__-test.js
  └── index.js

Blueprints that support pods structure look a little different. Let’s take the built-in controller blueprint as an example:

  ├── files
  │   ├── app
  │   │   └── __path__
  │   │       └── __name__.js
  └── index.js

  ├── files
  │   └── tests
  │       └── unit
  │           └── __path__
  │               └── __test__.js
  └── index.js


files contains templates for the all the files to be installed into the target directory.

The __name__ token is subtituted with the dasherized entity name at install time. For example, when the user invokes ember generate controller foo then __name__ becomes foo. When the --pod flag is used, for example ember generate controller foo --pod then __name__ becomes controller.

The __path__ token is substituted with the blueprint name at install time. For example, when the user invokes ember generate controller foo then __path__ becomes controller. When the --pod flag is used, for example ember generate controller foo --pod then __path__ becomes foo (or <podModulePrefix>/foo if the podModulePrefix is defined). This token is primarily for pod support, and is only necessary if the blueprint can be used in pod structure. If the blueprint does not require pod support, simply use the blueprint name instead of the __path__ token.

The __root__ token is substituted with either app or addon depending upon where it is being generated. This token is used to provide support for generating blueprints inside addons, and is only necessary if the blueprint needs to be generated into the addon directory of an addon. The presence of this token will cause an additional addon-import blueprint to be generated, which is simply a wrapper that re-exports the module in the addon directory to allow consumers to override addon modules easier.

The __test__ token is substituted with the dasherized entity name and appended with -test at install time. This token is primarily for pod support and only necessary if the blueprint requires support for a pod structure. If the blueprint does not require pod support, simply use the __name__ token instead.

Template Variables (AKA Locals)

Variables can be inserted into templates with <%= someVariableName %>.

For example, the built-in util blueprint files/app/utils/__name__.js looks like this:

export default function <%= camelizedModuleName %>() {
  return true;

<%= camelizedModuleName %> is replaced with the real value at install time.

The following template variables are provided by default:

  • dasherizedPackageName
  • classifiedPackageName
  • dasherizedModuleName
  • classifiedModuleName
  • camelizedModuleName

packageName is the project name as found in the project’s package.json.

moduleName is the name of the entity being generated.

The mechanism for providing custom template variables is described below.


Custom installation and uninstallation behaviour can be added by overriding the hooks documented below. index.js should export a plain object, which will extend the prototype of the Blueprint class. If needed, the original Blueprint prototype can be accessed through the _super property.

// index.js
module.exports = {
  locals: function(options) {
    // Return custom template variables here.
    return {};

  normalizeEntityName: function(entityName) {
    // Normalize and validate entity name here.
    return entityName;

  fileMapTokens: function(options) {
    // Return custom tokens to be replaced in your files
    return {
      __token__: function(options){
        // logic to determine value goes here
        return 'value';

  beforeInstall: function(options) {},
  afterInstall: function(options) {},
  beforeUninstall: function(options) {},
  afterUninstall: function(options) {}


Blueprint Hooks

As shown above, the following hooks are available to blueprint authors:

  • locals
  • normalizeEntityName
  • fileMapTokens
  • beforeInstall
  • afterInstall
  • beforeUninstall
  • afterUninstall


Use locals to add custom template variables. The method receives one argument: options. Options is an object containing general and entity-specific options.

When the following is called on the command line:

ember generate controller foo --type=array --dry-run

The object passed to locals looks like this:

  entity: {
    name: 'foo',
    options: {
      type: 'array'
  dryRun: true

This hook must return an object or a Promise which resolves to an object. The resolved object will be merged with the aforementioned default locals.


Use the normalizeEntityName hook to add custom normalization and validation of the provided entity name. The default hook does not make any changes to the entity name, but makes sure an entity name is present and that it doesn’t have a trailing slash.

This hook receives the entity name as its first argument. The string returned by this hook will be used as the new entity name.


Use fileMapTokens to add custom fileMap tokens for use in the mapFile method. The hook must return an object in the following pattern:

  __token__: function(options){
    // logic to determine value goes here
    return 'value';

It will be merged with the default fileMapTokens, and can be used to override any of the default tokens.

Tokens are used in the files directory (see files), and get replaced with values when the mapFile method is called.

beforeInstall & beforeUninstall

Called before any of the template files are processed and receives the same arguments as locals. Typically used for validating any additional command line options.

afterInstall & afterUninstall

The afterInstall and afterUninstall hooks receives the same arguments as locals. Use it to perform any custom work after the files are processed. For example, the built-in route blueprint uses these hooks to add and remove relevant route declarations in app/router.js.

Overriding Install

If you don’t want your blueprint to install the contents of files you can override the install method. It receives the same options object described above and must return a promise. See the built-in resource blueprint for an example of this.


Detailed List of Blueprints and Their Use

  • Acceptance Test
    • Generates an acceptance test for a given feature
    • Acceptance Tests are used to test flows within your application i.e. a signup, login, editing your account, etc.
    • ember generate acceptance-test signup
  • Adapter
    • This blueprint generates an Ember Data Adapter and its accompanying test
    • Options
      • Base Class
        • Application (default)
    • ember generate adapter application will generate an adapter called ‘ApplicationAdapter’ based off the DS.RESTAdapter by default.
    • ember generate adapter user will in turn call this adapter UserAdapter and inherit from the Application Adapter unless you specify a base class.
  • Adapter Test
    • This blueprint generates a unit test for a given ember data adapter.
    • ember generate adapter-test application
  • Addon Import
    • This blueprint generates an import wrapper in the app directory.
      • Import wrappers simply import a corresponding module from addon to allow easier overriding of a module in a project using the addon.
    • Used by ember-cli internally, it is only used when generating from inside addon projects.
  • Addon
    • Generates an addon blueprint and its definition.
      • This is the base blueprint for ember-cli addons.
    • ember addon awesome-addon
  • App
    • This is the default blueprint for ember-cli projects. It contains a conventional project structure and everything you will need to develop your ember apps.
    • This blueprint is most commonly encountered when starting a new application, as in ember new.
  • Blueprint
    • Generates a Blueprint and its corresponding definition. You can use this to create your own custom Blueprints. A Blueprint is essentially a bundle of templates with optional install logic.
    • ember generate blueprint example-blueprint
  • Component
    • Generates an Ember Component and its accompanying test.
    • A Component is your own app-specific tag with custom behaviour. They are basically views that are completely isolated. Usually used for building widgets.
    • Caveats
      • The component’s name must contain a hyphen
      • Slashes are not allowed
    • ember generate component nav-bar
  • Component Test
    • Generates a test for a given component
    • ember generate component-test nav-bar
  • Controller
    • Generates a Controller of a given name, with accompanying test.
    • ember generate controller users
  • Controller Test
    • Generates a unit test for a given Controller.
    • ember generate controller-test index
  • Helper
    • Generates a Handlebars Helper and its test. Commonly used for html reuse.
    • ember generate helper capitalize
  • Helper Test
    • Generates a test for a given helper
    • ember generate helper-test capitalize
  • HTTP Mock
    • This blueprint generates a mock endpoint with an ‘/api’ prefix that you can use to return canned data. This is commonly used as an API stub, which allows you to develop right away with the RESTAdapter instead of using fixtures.
    • ember generate http-mock users
  • HTTP Proxy
    • Generates a relative proxy to another server. You can use this to forward requests to a local development server, for example.
    • Options
      • Local Path
      • Remote URL
    • ember generate http-proxy
  • In-Repo Addon
    • Generates an addon within the same repository. Useful for project-specific addons.
    • The generator also creates a ‘lib’ directory, in which it stores the new addon.
    • ember generate in-repo-addon calendar
  • Initializer
    • Generates an Ember Initializer and its accompanying tests.
    • Common uses are to setup injection rules, like a current user, services, etc. You shouldn’t use them for fetching data via XHR, deferring readiness, or instantiating and using ‘container.lookup’. For more about initializers, view the API docs
    • ember generate initializer current-user
  • Initializer Test
    • Generates a test for a given initializer.
    • ember generate initializer-test current-user
  • Mixin
    • Generates a Mixin and its test. A mixin is an object whose properties can be added to other classes, like Controllers, Views, Routes, etc.
    • ember generate mixin filterable
  • Mixin Test
    • Generates a test for a given mixin.
    • ember generate mixin-test filterable
  • Model
    • Generates an Ember Data model and its test.
    • ember generate model user
  • Model Test
    • Generates a test for a given model.
    • ember generate model-test user
  • Resource
    • This blueprint generates a model, route, template, and their accompanying tests.
    • ember generate resource user
  • Route
    • Generates a route, its test, and then registers it with the router.
    • Type
      • Route (default)
      • Resource
    • ember generate route user
  • Route Test
    • Generates a test for a given route.
  • Serializer
    • Generates an Ember Data serializer.
    • ember generate serializer application
  • Serializer Test
    • Generates a test for a given ember data serializer
    • ember generate serializer-test application
  • Server
    • Generates a server directory for mocks and proxies.
    • ember generate server
  • Service
    • Generates a service and initializer for injections. These are commonly used for cases like websocket initialization, geolocation, feature flags, etc.
    • ember generate service geolocation
  • Service Test
    • Generates a unit test for a given service.
    • ember generate service-test geolocation
  • Template
    • Generates a template.
    • ember generate template user
  • Transform
    • Generates an Ember Data value transform, which are used to serialize and deserialize model attributes as they saved and loaded from the adapter. These can be useful for creating custom attributes.
    • ember generate transform foo
  • Transform Test
    • Generates a transform unit test.
    • ember generate transform-test foo
  • Util
    • Generates a utility module/function.
    • ember generate util foo
  • Util Test
    • Generates a util unit test.
    • ember generate util-test foo
  • View
    • Generates a View.
    • ember generate view user
  • View Test
    • Generates a view unit test.
    • ember generate view-test user

Developing Addons and Blueprints

Addons make it possible to easily share common code between applications. However, if an addon only covers a very project specific use-case, an In-Repo-Addon could be considered instead.

This guide will walk through the development cycle of a fictional addon ember-cli-x-button.


An addon can be installed with the install command:

ember install <package name>

To install the (fictional) x-button addon package:

ember install ember-cli-x-button


Ember CLI will detect the presence of an addon by inspecting each of your applications dependencies and search their package.json files for the presence of ember-addon in the keywords section (see below).

"keywords": [

Addon scenarios

The Ember CLI addons API currently supports the following scenarios:

  • Performing operations on the EmberApp created in the consuming application’s ember-cli-build.js
  • Adding preprocessors to the default registry
  • Providing a custom application tree to be merged with the consuming application
  • Providing custom express (server) middlewares
  • Adding custom/extra blueprints, typically for scaffolding application/project files
  • Adding content to consuming applications
  • Adding content to the consuming application’s tests directory (via test-support/)

Addon CLI options

Ember CLI has an addon command with some options:

ember addon <addon-name> <options...>

Note: An addon can NOT be created inside an existing application.

Create addon

To create a basic addon: ember addon <addon-name>

Running this command should generate something like the following:

ember addon ember-cli-x-button
version x.y.zz
  create .bowerrc
  create .editorconfig
  create tests/dummy/.jshintrc
  create index.js

Installing packages for tooling via npm
Installed browser packages via Bower.

Addon conventions

The addon infrastructure is based on “convention over configuration” in accordance with the Ember philosophy. You are encouraged to follow these conventions to make it easier on yourself and for others to better understand your code. The same applies for addon blueprints.

Addon project structure

The addon project created follows these structure conventions:

  • app/ - merged with the application’s namespace.
  • addon/ - part of the addon’s namespace.
  • blueprints/ - contains any blueprints that come with the addon, each in a separate directory
  • public/ - static files which will be available in the application as /your-addon/*
  • test-support/ - merged with the application’s tests/
  • tests/ - test infrastructure including a “dummy” app and acceptance test helpers.
  • vendor/ - vendor specific files, such as stylesheets, fonts, external libs etc.
  • ember-cli-build.js - Compilation configuration
  • package.json - Node meta-data, dependencies etc.
  • index.js - main Node entry point (as per npm conventions)


The generated addon package.json file looks something like this:

  "name": "ember-cli-x-button", // addon name
  "version": "0.0.1", // version of addon
  "directories": {
    "doc": "doc",
    "test": "test"
  "scripts": {
    "start": "ember server",
    "build": "ember build",
    "test": "ember test"
  "repository": "",
  "engines": {
    "node": ">= 0.10.0"
  "keywords": [
    // add more keywords to better categorize the addon
  "ember-addon": {
    // addon configuration properties
    "configPath": "tests/dummy/config"
  "author": "", // your name
  "license": "MIT", // license
  "devDependencies": {
    "body-parser": "^1.2.0",
    ... // add specific dev dependencies here!

Let’s add some meta data to categorize the addon a little better:

"keywords": [

Addons depending on other addons

If your addon depends on another addon, install it as a dependency in your package.json:

// ...
"dependencies": {
  "ember-ajax": "^0.7.1"

An application that consumes your addon will automatically install and bundle dependencies specified this way.

Addon entry point

An addon will leverage the npm conventions, and look for an index.js as the entry point unless another entry point is specified via the "main" property in the package.json file. You are encouraged to use index.js as the addon entry point.

The generated index.js is a simple JavaScript Object (POJO) that you can customize and expand as you see fit.

// index.js
module.exports = {
  name: 'ember-cli-x-button'

During the build process, the included hook on your addon will be called, allowing you to perform setup logic or modify the app or addon:

// index.js
module.exports = {
  name: 'ember-cli-x-button',
  included: function(app, parentAddon) {
    this._super.included.apply(this, arguments);
    var target = (parentAddon || app);
    // Now you can modify the app / parentAddon. For example, if you wanted
    // to include a custom preprocessor, you could add it to the target's
    // registry:
    //     target.registry.add('js', myPreprocessor);

The exported object extends the Addon class. So any hooks that exist on the Addon class may be overridden by addon author.

Configuring your ember-addon properties

By default, the "ember-addon" hash in the package.json file has the "configPath" property defined to point to the config directory of the test dummy application.

Optionally, you may specify whether your ember-addon must run "before" or "after" any other Ember CLI addons. Both of these properties can take either a string or an array of strings, where the string is the name of the another Ember CLI addon, as defined in the package.json of the other addon.

Optionally, you may specify a different name for the "defaultBlueprint". It defaults to the name in the package.json. This blueprint will be run automatically when your addon is installed with the ember install command.

Optionally, you may specify the "demoURL" property with the fully qualified URL of a website showing your addon in action. Sites like Ember Addons and Ember Observer will display a link to "demoURL".

"ember-addon": {
  // addon configuration properties
  "configPath": "tests/dummy/config",
  "before": "single-addon",
  "defaultBlueprint": "blueprint-that-isnt-package-name",
  "demoURL": "",
  "after": [

Addon ember-cli-build

The addon’s ember-cli-build.js is only used to configure the dummy application found in tests/dummy/. It is never referenced by applications which include the addon.

If you need to use ember-cli-build.js, you may have to specify paths relative to the addon root directory. For example to configure ember-cli-less to use app.less in the dummy app:

// ember-cli-build.js
var EmberAddon = require('ember-cli/lib/broccoli/ember-addon');

var app = new EmberAddon({
  lessOptions: {
    paths: ['tests/dummy/app/styles/'],
    outputFile: 'dummy.css'

module.exports = app.toTree();

Addon Components

The actual code for the addon goes in addon/components/x-button.js

import Ember from 'ember';

export default Ember.Component.extend({
  tagName: 'button',

  setupXbutton: Ember.on('didInsertElement', function() {
    // ...

  teardownXbutton: Ember.on('willDestroyElement', function() {

In order to allow the consuming application to use the addon component in a template directly you need to bridge the component via your addon’s app/components directory. Just re-export your component:

// app/components/x-button.js
export { default } from 'ember-cli-x-button/components/x-button';

This setup allows others to modify the component by extending it while making the component available in the consuming applications namespace. This means anyone who installs your x-button addon can start using the component in their templates with {{x-button}} without any extra configuration.

Default Blueprint

A blueprint with the same name as the addon (unless explicitly changed, see above) will be automatically run after install (in development, it must be manually run after linking). This is where you can tie your addon’s bower dependencies into the client app so that they actually get installed.

To create the blueprint, add the file blueprints/ember-cli-x-button/index.js. This follows the usual Ember blueprints naming conventions.

// blueprints/ember-cli-x-button/index.js
module.exports = {
  normalizeEntityName: function() {}, // no-op since we're just adding dependencies

  afterInstall: function() {
    return this.addBowerPackageToProject('x-button'); // is a promise

Working with Dependencies

You can pull in addons, npm packages, and bower packages, in your blueprint, by using various hooks provided to you. They are as follows:

  • addAddon(s)ToProject Adds an addon to the project’s package.json and runs its defaultBlueprint if it provides one.
  • addBowerPackage(s)ToProject Adds a package to the project’s bower.json.
  • addPackage(s)ToProject Adds a package to the project’s package.json.

Each of these returns a promise, so it is all thenable. The following is an example of each of these:

// blueprints/ember-cli-x-button/index.js
module.exports = {
  normalizeEntityName: function() {}, // no-op since we're just adding dependencies

  afterInstall: function() {
    // Add addons to package.json and run defaultBlueprint
    return this.addAddonsToProject({
      // a packages array defines the addons to install
      packages: [
        // name is the addon name, and target (optional) is the version
        {name: 'ember-cli-code-coverage', target: '0.3.9'},
        {name: 'ember-cli-sass'}
    .then(() => {
      // Add npm packages to package.json
      return this.addPackagesToProject([
        {name: 'babel-eslint'},
        {name: 'eslint-plugin-ship-shape'}
    .then(() => {
      return this.addBowerPackagesToProject([
        {name: 'bootstrap', target: '3.0.0'}

Importing Dependency Files

As stated earlier the included hook on your addon’s main entry point is run during the build process. This is where you want to add import statements to actually bring in the dependency files for inclusion. Note that this is a separate step from adding the actual dependency itself—done in the default blueprint—which merely makes the dependency available for inclusion.

// index.js
module.exports = {
  name: 'ember-cli-x-button',

  included: function(app) {
    this._super.included.apply(this, arguments);

    app.import(app.bowerDirectory + '/x-button/dist/js/x-button.js');
    app.import(app.bowerDirectory + '/x-button/dist/css/x-button.css');

In the example file, the included hook is used. This hook is called by the EmberApp constructor and gives access to the consuming application as app. When the consuming application’s ember-cli-build.js is processed by Ember CLI to build/serve, the addon’s included function is called passing the EmberApp instance.

Importing Static Files

To import static files such as images or fonts in the application include them in /public. The consuming application will have access to them via a directory with your addon’s name.

For example, to add an image, save it in /public/images/foo.png. Then from the consuming application access it as:

  .foo {background: url("/your-addon/images/foo.png");}


If you want to add content to a page directly, you can use the content-for tag. An example of this is {{content-for 'head'}} in app/index.html, which Ember CLI uses to insert it’s own content at build time. Addons can access the contentFor hook to insert their own content.

// index.js
module.exports = {
  name: 'ember-cli-display-environment',

  contentFor: function(type, config) {
    if (type === 'environment') {
      return '<h1>' + config.environment + '</h1>';

This will insert the current environment the app is running under wherever {{content-for 'environment'}} is placed. The contentFor function will be called for each {{content-for}} tag in index.html.

Writing to the Command Line

Every addon is sent an instance of the parent application’s command line output stream. If you want to write out to the command line in your addon’s index.js file, you should use this.ui.writeLine rather than console.log. This will make the output obey the --silent flag available with many ember-cli commands.

// index.js
module.exports = {
  name: 'ember-cli-command-line-output',

  included: function(app) {
    this._super.included.apply(this, arguments);
    this.ui.writeLine('Including external files!');

Advanced customization

If you want to go beyond the built in customizations or want/need more advanced control in general, the following are some of the hooks (keys) available for your addon Object in the index.js file. All hooks expect a function as the value.

includedCommands: function() {},
blueprintsPath: // return path as String

Documentation for the addon hooks is available here.

An example of advanced customization can be found here and for server middleware here.

Testing the addon with QUnit

The addon project contains a /tests directory which contains the necessary infrastructure to run and configure tests for the addon. The /tests directory has the following structure:


The /dummy directory contains the basic layout of a dummy app to be used for to host your addon for testing. The /helpers directory contains various QUnit helpers that are provided and those you define yourself in order to keep your tests concise. The /unit directory should contain your unit tests that test your addon in various usage scenarios. To add integration (acceptance) tests add an `integration/’ directory.

test-helper.js is the main helper file that you should reference from any of your unit test files. It imports the resolver helper found in /helpers used to resolve pages in the dummy app. index.html contains the test page that you can load in a browser to display the results of running your integration tests.

Writing unit tests

The following is an example of a simple QUnit unit test, placed in tests/unit/components.

// tests/unit/components/button-test.js

import { test, moduleForComponent } from 'ember-qunit';
import startApp from '../../helpers/start-app';
import Ember from 'ember';

var App;

moduleForComponent('x-button', 'XButtonComponent', {
  beforeEach: function() {
    App = startApp();
  afterEach: function() {, 'destroy');

test('is a button tag', function(assert) {
  assert.equal('BUTTON', this.$().prop('tagName'));


// more tests follow...

For how to run and configure tests, see the Ember CLI Testing section.

Generating files in the dummy app

You can generate most of ember-cli’s built-in blueprints into your tests/dummy/app directory to speed up building a dummy app to use for testing. Any blueprint that generates into an /app directory is currently supported:

ember g <blueprint-name> <name> --dummy

For instance:

ember g component taco-button --dummy

Will generate:


Note that in the above example, the addon-import and component-test were not generated. The --dummy option generates the blueprint as if you were in a non-addon project.

You can also create your own blueprints that can generate into the dummy directory. The primary requirement is that the blueprint contains a __root__ token in the files directory path.

      __root__/     <-- normally "app/"

Create blueprint

A blueprint is a bundle of template files with optional installation logic. It is used to scaffold (generate) specific application files based on some arguments and options. For more details see generators-and-blueprints). An addon can have one or more blueprints.

To generate a blueprint for your addon:

ember generate blueprint <blueprint-name>

By convention, the main blueprint of the addon should have the same name as the addon itself:

ember g blueprint <addon-name>

In our example:

ember g blueprint x-button

This will generate a directory blueprints/x-button for the addon where you can define your logic and templates for the blueprint. You can define multiple blueprints for a single addon. The last loaded blueprint wins with respect to overriding existing (same name) blueprints that come with Ember or other addons (according to package load order.)

Blueprint conventions

Blueprints are expected to be located under the blueprints directory in the addon root, just like blueprints overrides in your project root.

If you have your blueprints in another directory in your addon, you need to tell ember-cli where to find them by specifying a blueprintsPath property for the addon (see advanced customization section below).

If you are familiar with Yeoman (or Rails) generators, blueprints follow very similar conventions and structure.

To dive deeper into blueprints design, please see the Ember CLI blueprints where you get a feeling for the blueprints API.

Blueprints file structure


Note that the special file or directory called __name__ will create a file/directory at that location in your app with the __name__ replaced by the first argument (name) you pass to the blueprint being generated.

ember g x-button my-button

Will thus generate a directory app/components/my-button in the application where the blueprint generator is run.

While you are developing and testing, you can run npm link from the root of your addon project. This will make your addon locally available by name.

Then run npm link <addon-name> in any hosting application project root to make a link to your addon in your node_modules directory, and add the addon to the package.json. Any change in your addon will now directly take effect in any project that links to it this way (see npm-tricks for more details).

Remember that npm link will not run the default blueprint in the same way that install will, so you will have to do that manually via ember g.

For live reload when developing an addon use the isDevelopingAddon hook:

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

While testing an addon using npm link, you need an entry in package.json with your addon name, with any valid npm version: "<addon-name>":"version". Our fictional example would require "ember-cli-x-button": "*". You can now run ember g <addon-name> in your project.

Publish addon

Use npm and git to publish the addon like a normal npm package.

npm version 0.0.1
git push origin master --follow-tags
npm publish

Using a private repository

You can upload your addon code to a private git repository and call ember install with a valid git URL as the version.

If you are using the URL formats can be found here.

When using the git+ssh format, the ember install command will require there to be an available ssh key with read access to the repository. This can be tested by running git clone ssh:[email protected]:user/project.git.

When using the git+https format, the ember install command will ask you for the account password.

Install and use addon

In order to use the addon from you hosting application:

To install your addon from the repository:

ember install <your-addon-name-here>.

For our x-button sample addon:

ember install ember-cli-x-button my-button.

This will first install the x-button addon from npm. Then, because we have a blueprint with the same name as our addon, it will run the blueprint automatically with the passed in arguments.

Updating addons

You can update an addon the same way you update an Ember app by running ember init in your project root.

Full example

For a good walkthrough of the (recent) development of a real world addon, take a look at: Creating a DatePicker Ember CLI addon


Addons sepecific to your project can be created inside your repo and are generated in the projects lib directory in a folder with the name of the in-repo-addon, e.g. /lib/in-repo-addon-name and follow the same file structure as a normal addon.

Some advantages of using an in-repo-addon, instead of an addon outside of your application (repo), are:

  • Sandbox for developing a feature that you may want to share as an addon in the future
  • Having all the benefits of addon isolation but without the need to publish or npm link

Use in-repo-addon argument with the ember generate command:

ember generate in-repo-addon in-repo-addon-name

(Replace in-repo-addon-name with the name of your addon.)

Using a stylesheet with an in-repo-addon

For your in-repo-addon stylesheet, name the file addon.css and place it in the styles directory, e.g /lib/in-repo-addon-name/addon/styles/addon.css This avoids any conflict with the parent application’s app.css file

Likewise if your Ember CLI application uses .less or .scss, use the appropriate file extension for your addon stylesheet file.

Using templates with an in-repo-addon

In order to complile HTMLBars templates that are part of your in-repo-addon, your package.json file will need to include following dependencies:

  • babel-plugin-htmlbars-inline-precompile
  • ember-cli-babel
  • ember-cli-htmlbars
  • ember-cli-htmlbars-inline-precompile

(Use the same versions found in your Ember CLI Application’s package.json)

Broccoli build options for in-repo-addons

To ensure that you can use babel.js and related polyfills with your in-repo-addon add babel options to the included hook of the in-repo-addon index.js:

module.exports = {
  name: 'in-repo-addon-name',

  isDevelopingAddon: function() {
    return true;

  included: function(app, parentAddon) {
    var target = (parentAddon || app);
    target.options = target.options || {};
    target.options.babel = target.options.babel || { includePolyfill: true };
    return this._super.included.apply(this, arguments);

Generating an in-repo-addon blueprint

To generate a blueprint for your in-repo-addon:

ember generate blueprint <blueprint-name> --in-repo-addon <in-repo-addon-name>

When generating a blueprint, a shorthand argument -ir or -in-repo can be used in place of --in-repo-addon.