search

ember-learn / cli-guides

Step-by-step guides and tutorials for using the ember-cli to create apps and addons
https://cli.emberjs.com
MIT License
25 stars 76 forks source link

Document Addon authoring under v2 spec #191

Open mehulkar opened 4 years ago

mehulkar commented 4 years ago

As mentioned by @ef4 in https://github.com/emberjs/rfcs/pull/578#issuecomment-643481309, one of the next steps towards modernizing Ember CLI's build system is teaching Addon authors how to convert their addons to be in native v2 spec.

Some of this is described here: https://github.com/embroider-build/embroider/blob/v0.19.0/ADDON-AUTHOR-GUIDE.md#support-level-embroider-native, but we need this documentation in the CLI Guides in a more official format.

rwjblue commented 4 years ago

I think the main blocker here is providing a shim layer that addon authors can use in order to author their addons that can be consumed by both Embroider and classic Ember CLI build pipeline. I believe that the Embroider folks (I have spoken to both @ef4 and @thoov about this fairly recently) are planning this work, but I'm not sure of the timeline. Once that shim layer exists (and is tested) ember-cli will make ember addon foo emit an addon in that format.

In the meantime, we could totally document (for addon authors) how to test their addons with Embroider (to ensure they are generally compatible). @kiwiupover recently mentioned this in a FastBoot meeting, and referenced this PR where he added some Embroider tests https://github.com/ivanvotti/ember-svg-jar/pull/160. Documenting that kind of thing in the addon author section of these guides seems like a reasonable next step.

mehulkar commented 4 years ago

Yeah I saw that @simonihmig had gotten it running in ember-bootstrap as well: https://github.com/kaliber5/ember-bootstrap/pull/930.

I think the main blocker here is providing a shim layer that addon authors can use in order to author their addons that can be consumed by both Embroider and classic Ember CLI build pipeline.

So is it correct to say that addons can not be written in v2 until this shim is ready?

In the meantime, we could totally document (for addon authors) how to test their addons with Embroider

I'll get this started! @jenweber, I noticed there's a blank testing.md page (added in #40): https://github.com/ember-learn/cli-guides/blob/master/guides/writing-addons/testing.md. It seems kind of hidden away, but is that a good place to put this content?

rwjblue commented 4 years ago

So is it correct to say that addons can not be written in v2 until this shim is ready?

Yes, that is essentially true, though concretely it is probably possible to author an addon that only works with Embroider (e.g. is not compatible with apps that use the classic build system) but I don't think any of us really think it is a good idea to bifurcate (especially when we legitimately think the shim layer will be straight forward and fully compatible).

ef4 commented 4 years ago

though concretely it is probably possible to author an addon that only works with Embroider

Yeah, in practice even this is hard, because you're always going to have some v1 addons in the build, and those addons want to see the traditional instance of EmberApp, and the EmberApp wants to see traditional instances of all the addons, so at that point your v2 addon really needs to be able to present itself as v1.

I have time booked this afternoon to work on writing down the remaining TODOs for getting this working.