Implementation techniques used in ember-micro-addon

ember-micro-addon-implementation.md

How is the flat file structure working within an ember-app?

The addon's entry point, index.js is key here.

The addon exposes several hooks during addon/app build-time, several of which are treeForX where X is some part of the app/addon. In our case, depending on the addon type, we hook into one or more of theese hooks, at which point, we restructure and rename the files on the fly, so they're conventionally placed and named by the time the parent app tries to load them.

For components

• treeForApp moves component.js to app/components/addonName.js
• treeForTemplate moves template.hbs to app/templates/components/addonName.hbs
• treeForAddon moves style.css to addon/styles/addonName.css
  • Optionally, we could also add a compile step from .scss here. I verified it and it works, but I wanted to keep things light for now.
  • Moving it to app/styles/addonName.css would also work, but this way, the resulting .cssends up in vendor.css and this would make it end up in appName.css

For libraries

• treeForApp moves library.js to app/lib/addonName.js

For helpers

• treeForApp moves helper.js to app/helpers/addonName.js

How is the addon conversion to the proper structure working?

It's just basic node file/folder manipulation. I'm using the fs-extra library, which makes automatic overwriting and creation of files/folders slightly easier. The same file mapping as in the previous section is being done, except the files are now being copied to their proper location inside the newly created dist folder.

Additionally, I'm explicitly creating blank index.js files, since we're now making a proper ember addon and the various treeForX operations are no longer required.

How are the ember micro:x commands working

I have a set of commands defined in /lib/commands with an index script which imports/exports all of them. The addon's index.js then provides an includedCommands through which these commands are loaded.

Unfortunately, with the way ember-cli addon discovery works, it seems it was never intended for us to create additional ember commands that can be called globally. Instead, they only work from the project folder where the addon providing them is installed. If this ever changes, it will make things simpler.

When calling ember micro:component someaddon from some ember project folder

• ember-cli addon discovery finds our addon in the current project folder and figures out the micro:component command is defined there
• command gets called from lib/commands/component.js - verifyAndRun function is executed
• command calls task from lib/tasks/component.js - task does its thing

How are global CLI commands working

We're using an npm feature for this.

In package.json, we can define commands added by the npm package through the "bin" property:

"bin": {
    "some-command": "path/to/script/that/executes/command.js",
    "some-other-command": "path/to/some/other/script.js"
}

If the addon is installed locally, then these commands become available from the current folder. If it is installed globally, then they are available as global command line commands.

In our case, I implemented very basic wrappers which simply call ember-commands when one of the console commands is executed.

When calling ember-micro:component from any location

• A global command which was automatically added when installing the ember-micro-addon NPM package gets called
• The global command executes the script lib/cli/component based on how it was defined in package.json
• Script is a wrapper to lib/commands/component.js
• command gets called from lib/commands/component.js - verifyAndRun function is executed
• Command calls task from lib/tasks/component.js

Questions

1. Does or will ember-cli support the addition of global ember-commands, via installing the ember-addon globally, the way npm already does?
2. What is the proper, conventional way to automatically/implicitly include styles into an ember app through an ember addon?