Blueprint

A blueprint is a bundle of template files with optional install logic.

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

blueprints/controller
├── files
│   ├── app
│   │   └── __path__
│   │       └── __name__.js
└── index.js

blueprints/controller-test
├── files
│   └── tests
│       └── unit
│           └── controllers
│               └── __test__.js
└── index.js

Files

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

Index.js

Custom installation and uninstallation behavior 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.

module.exports = {
  locals(options) {
    // Return custom template variables here.
    return {};
  },

  normalizeEntityName(entityName) {
    // Normalize and validate entity name here.
    return entityName;
  },

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

  filesPath(options) {
    return path.join(this.path, 'files');
  },

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

};

Blueprint Hooks

beforeInstall & beforeUninstall

Called before any of the template files are processed and receives the options and locals hashes as parameters. Typically used for validating any additional command line options or for any asynchronous setup that is needed. As an example, the controller blueprint validates its --type option in this hook. If you need to run any asynchronous code, wrap it in a promise and return that promise from these hooks. This will ensure that your code is executed correctly.

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.