I’ve found it very hard to get started building quality Ember CLI addons whose functionality involves more than simply adding some files to the app or addon directories or importing static vendor files in the addon’s index.js file. After two weeks of research and reading through the source of plenty of addons I’m still pretty green and I do not believe I am alone in feeling this.
Side note: I understand some of the following issues might be Broccoli issues. However, given the Ember community’s significant and unique reliance on Broccoli and Broccoli’s sparse documentation, I think it’s a valid point to bring up here.
Proposal
I’d like to see some really solid guides available for the Ember addon API but I don’t have enough experience to write them. Some topics I’d love to see covered are:
The methods that could be part of an addon, when to use each method, what to return from each, and some example use cases. The ‘methods’ I am referring to are: includedCommands, blueprintsPath, postBuild, treeFor, treeForVendor, included, postprocessTree, serverMiddleware, and any others.
Docs for the methods available inside methods in an addon, and example use cases. These methods include: this.concatFiles, this.mergeTrees, and basically everything in ember-cli/lib/models/addon.js.
Example walkthroughs or repos explaining the architecture of 5 common use cases for plugins. For example:
Sharing common Ember code between applications (e.g. adding a few Ember components)
Compiling files to modules 1-to-1 (e.g. Compiling Handlebars files into Ember templates)
Replacing a file type (e.g. Markdown to Handlebars)
Parsing all files in a tree and adding another tree to the app (e.g. javascript documentation builder, SASS compiling/concatenation, Modernizr custom build like grunt-modernizr)
Extended documentation for common Broccoli plugins used with Ember addons (e.g. Broccoli Filter, Broccoli Writer, Broccoli Funnel)
Examples of the types of plugins that are not suited for Broccoli-based Ember addons
The goal for all of the above would be to write a practical guide(s) bringing together the broccoli API and Ember addon API with best practices for how to decide on the best architecture to minimize build times. Perhaps this is a good joint Ember/Broccoli project.
First and foremost, do you believe this would be a worthwhile time investment, given everything else going on in the world of Ember right now? Secondly, are the points that I described above the points you would like to see covered in such a guide? Thirdly, would you be interested in helping put together such a guide?
@jcope2013 Thanks for the link. I see that guide touching on the same point many other blog posts have - the simple ‘adding some new modules to the app.’ Although that’s a very common use case and definitely one the guide should cover, there are not many decisions the developer has to make in building that addon. I see the addon guides being very beneficial when the developer is doing more than just adding some modules. Namely, when adding a lot to the addon’s index.js file.
As for what platform to utilize, I would see this being an initial PR to ember-cli or the Ember CLI website that adds some ‘addon guides’ resource many people could contribute to as Ember CLI grows. This would not be automated documentation à la Ember documentation but rather carefully curated content with at least one person who has the direct responsibility of overseeing guide maintenance and growth. Of course, I am open to other platform ideas too though I think this should remain pretty centralized with the rest of the Ember CLI guides.
I completely agree. I’ve written a few addons and each time I’m attempting to do something a little different than last which results in diving deep into the source to figure out how the methods behave.
I’m happy to take the lead reaching out to people, developing a skeleton for the guides, bringing content together, thinking through the UX, etc. However, if there’s someone more qualified that wants to lead this then that’s probably a better idea!
@stefan The more I’ve thought about it, the more I see this being a section on the Ember CLI website. One potential obstacle here is the site isn’t really set up for resource-based navigation because it acts more like an index page. Would that be something you’re open to changing up with a horizontal nav bar for primary nav? For example, the current index page might become ‘docs’ and the ember-addons might be ‘addons’, or something like that.
I think there is a lot of value in the use case documentation. I presume that the specific API and low level documentation will organically get better and richer over time. But just understanding how the addon ecosystem can and should work would be very useful to read. So definitely would be excited to read case study type guides.