Documenting ember vs ember-cli

[kodonnell]

Our organisation has just started with ember (using yeoman generators) and serious front-end development in general -- so we're pretty green, and forgive any of my misunderstandings. Anyway, the main issue is that we keep reading about 'ember' and 'ember-cli' ... and we can't really find a good discussion of how the two are different. (I've spent a fair while looking, and at least it's not obvious to me.) For example, it took me a long while to figure out that 'ember addons' are really 'ember-cli addons', etc. I'm trying to convince my colleagues at work tomorrow that we should we use ember-cli, but I'd like to be more certain myself, and be able to present a stronger case.

Off the top of my head, the following might be useful to have documented somewhere:

1. Is ember-cli essentially a tool for creating ember apps? I.e. are you still just building an ember app, just quicker, and better(er)?
2. Why does there seem to be different code syntax? The two may be equivalent, but the Yeoman ember generator and the ember-cli generator differ, e.g. the Yeoman generator just defines something (App.ProjectController = ...) whereas ember-cli seems to favour exports (export default ...). Are these equivalent?
3. If the answer to (1) is 'no' or (2) is 'because they're fundamentally different', then how easy is it to convert between ember and ember-cli (if this makes sense as a question)? E.g. if our company chooses to go with ember-cli, and then realise it's insufficient in some particular area, how hard is it to revert to 'standard' ember? I've spent a fair while doing the reverse (trying to convert our existing app into an ember-cli one), and it hasn't been as straightforward as copy-and-pasting etc. (A side issue might be that: the ability to convert an existing ember app into an ember-cli one, if that doesn't already exist.)
4. If we're planning to use ember.js, should we really be using ember-cli? Are there valid reasons not to? Even if we use it in a limited fashion (for generators and tests), but use e.g. Grunt to replace some of it's features?
5. Finally, a link to documentation for ember-cli, if any. Ember.js has great documentation, but that for ember-cli is pretty sparse.

Any comment would be much appreciated.

[quaertym]

I was at the same situation about a year ago, so these are my answers to your questions.

1. Ember-CLI is the recommended way to build ember apps. Considering the incredible community effort behind ember-cli, I think it would be unwise to not use it. Ember-CLI is both powerful and flexible. See The Road to Ember 2.0 to understand the roadmap for Ember, directly quoting from Big Bets section:

   In Ember 2.0, Ember CLI and ES6 modules will become first-class parts of the Ember experience. We will update the website, guides, documentation, etc. to teach new users how to build Ember apps with the CLI tools and using JavaScript's new module syntax.
   While globals-based apps will continue to work in 2.0, we may introduce new features that rely on either Ember CLI or ES6 modules. You should begin moving your app to Ember CLI as soon as possible.

2. If you are not familiar, you should read about globals vs modules. Modules are the way forward and they are better for modularity, clarity, code-sharing, testing etc.

3. I have converted a large app to ember-cli before. It was mostly copy-paste and with the help of generators, the task becomes easier. In our case, it took a few hours. I am not sure if you ever need the opposite. If ember-cli is insufficient in some particular area(also the addons do not help let's say) then I guess it should be considered as a bug for ember-cli. However it would be harder to convert from ember-cli to something else since ember-cli does so many things for you.

4. You can use ember without ember-cli, that's possible. However I cannot think of valid reasons not to. I have switched from a grunt based workflow and I am glad I did. Ember-CLI uses broccoli as its build tool and it is way better than Grunt(In my experience, a large gruntfile is so fragile and no one wants to touch that).

5. The main resource for ember-cli is the website. It is getting better everyday.

[stefanpenner]

Finally, a link to documentation for ember-cli, if any. Ember.js has great documentation, but that for ember-cli is pretty sparse.

ember-cli only documents itself, deferring ember related documentation to the ember site. Unfortunately at this time the emberjs.com guides are slow to catchup. @tomdale has been working on some re-think of the ember guides to address this.

@tomdale i believe the above questions make sense, and should help guide future doc work.

[tomdale]

Good timing, @bsclifton just submitted emberjs/website#1956 which hopefully addresses some of these concerns. We are going to do the work to incorporate the Ember CLI content into the Ember guides. We've been way too slow about this and it's embarrassing. ;)

[kodonnell]

Awesome, thanks @quaertym, that was really helpful -- an email recommending ember-cli has been sent to the team, and you're quoted!

@tomdale & @stefanpenner, thanks. Our company, despite having little frontend experience, essentially decided "we want to do an awesome frontend, so let's go with Ember". So we started (using Yeoman), but had no idea about ember-cli until we started looking at addons. If there are other users in this bracket, these documentation changes will be really useful.

[harbulot]

@quaertym You're saying you can't think of any valid reason not to use ember-cli, here is a possible one: dealing with existing code, not all of which may be using Ember at all. (You're saying you've converted a large app to ember-cli, but that was presumably a large Ember app.)

A lot of emphasis seems to be put on applications that have been created using Ember (cli or not). This makes sense, but unfortunately, there are a number of rich-client applications out there that have not been developed using that model, and where some of the existing parts of code simply don't fit very well with Ember's expectations. (This doesn't have to be "very old" code.)

Considering an application that would have been developed with other frameworks, or more custom JavaScript code, even using libraries like jQuery, it is still possible with Ember 1.10.0 to use components within that application, without requiring the whole application to migrate towards Ember.js all at once (or even to have to use its route system, since it's possible to use App.Router.reopen({ location: 'none' });) for example, and use other events to reload the models when necessary). This way, you can start using Ember.js progressively, simply by including its script. You can try features step by step, without having to take the risk of switching your entire project to Ember.js, and without having to change your build model. This is a very positive aspect of Ember.

This seems to be far more difficult if ember-cli becomes more or less mandatory. I don't know whether the plans are to drop "non-CLI" usage altogether eventually, but it's clear that removing the non-CLI documentation makes the process of gradual or partial integration more time consuming (at best, if you can, you still have to work out manually what ember-cli does under the hood), and it becomes a much riskier route.

For example, "disabling prototype extensions" in the 1.10.0 documentation is documented in a way that's relatively straightforward to use without ember-cli:

window.EmberENV = {};
EmberENV.EXTEND_PROTOTYPES = false;

It's a different story in the 1.11.0 documentation. You then have to work out how that could be integrated in your existing code, which may just not have that config/environment.js file at all:

config/environment.js:

ENV = {
  EmberENV: {
    EXTEND_PROTOTYPES: false
  }
}

I'm not sure whether @tomdale and the rest of the team have taken this into consideration, but I would suspect there are a number of potential users for whom the risk of having to do an all-at-once migration towards Ember (i.e. an almost complete rewrite of their code in many cases) as a deterrent to try to use Ember at all.

[stefanpenner]

@harbulot we are aware, and ember will continue to work without a build step.

For those users interested in going off the beaten trail, it will continue to work. But without a common base, many things like for example, the majority of addons @ http://www.emberaddons.com/ will not be available.

It likely is a good idea to compose a guide entry on ember without ember-cli. Unfortunately, this is low in the triage order. If someone is interested in creating and maintaining such a guide, that would be wonderful.

[harbulot]

@stefanpenner Perhaps a better way to document Ember with and without cli would be to keep them both in the documentation. I guess having two sets of manuals will make it harder to keep them in sync in the long run.

In terms of presentation, perhaps one way to display code samples (like the one in my previous comment) would be to have a tab for each: cli and non-cli (quite similar to the "Write" and "Preview" tabs here when writing a comment on GitHub).

[tomdale]

@harbulot As a framework that believes in strong opinions and having a single "happy path", I think it would be confusing to users to have to select a mode to view the sample documentation in. The majority of Ember users will end up using Ember CLI, so we're going to orient the documentation around that.

As @stefanpenner mentioned, we will continue to support the no-build-step path for some time, but the documentation will not lead people in that direction unless they explicitly go looking for it. We believe that Ember CLI is a much better experience for almost everyone.

[harbulot]

@tomdale It depends on what kind of applications you're aiming Ember at. If it's for brand new applications that are developed from scratch, sure, the strong opinion approach and Ember CLI might give you a happy path.

The minute you have to deal with some legacy code (by legacy, I don't mean old, I mean something that was written before using Ember CLI was considered), or if you have to integrate with other frameworks or even other build systems (even with reasonably recent code), the Ember CLI push can cause much more problems and frustration (definitely not a happy path).

With the non-CLI approach, someone willing to make their existing application evolve (be it based on Java, PHP, or other) can try it out, without much risk, and introduce Ember components progressively, without having to break or modify extensively what they already have (you just add a couple of JS scripts).

In contrast, the Ember CLI approach requires abrupt changes, which might simply not be realistic to expect without a more substantial rewrite of existing applications.
By (almost) forcing a radical build/deployment system, it just makes it harder to try out whether it's worth using Ember in a existing application. In this case, not only Ember requires a change in the application (which is to be expected), but it may require changes in how the entire project is built, deployed and tested.
This seems to create two mountains to climb: the learning curve for Ember itself, and working out a good way to deploy and test whatever you want to try. The latter is particularly useful to evaluate yourself or convince others involved in a project that it's worth looking at this technology.

I realise "opinionated" frameworks provide a feeling of freedom at first (and can be trendy), but like anything, being too opinionated can create additional problems when it comes to integrating with other features and requirements, which many real-world applications will generally have to do.

Sure, most Ember users will certainly end up using Ember CLI, but that may just be because others who could have used Ember simply found it too complex or risky to attempt to use Ember at all in the context of their applications, in part due to the focus on CLI.

[tomdale]

@harbulot Sure, those are all important tradeoffs we've considered carefully, both on the core team and in the community generally. As I said, we will continue to support this use case for sometime. That being said, we would rather a few people have a great experience than many people have a mediocre one.

By making the old school way a mainline part of the documentation, we increase the odds that someone takes that path, and when they do that, they really are cutting themselves off from the greater Ember community, including many tutorials, blog posts, addons, etc. that assume Ember CLI.

I'd rather be extremely good for greenfield applications than mediocre for bolting on to existing applications. I happen to think we can do a good job at both, but greenfield/Ember CLI will continue to be the focus of the happy path since that's where the growth potential is. After all, there are infinite number of apps to be written in the future, and a finite number of existing apps that will be ported. ;)

[stefanpenner]

than mediocre for bolting on to existing applications.

we have been having some ideas to make bolting on (even with ember-cli) actually extremely nice.

cc @mixonic @trek @mmun

[kodonnell]

Having posted this question as a newbie, I can possible reflect as a marginally more experienced user:

As @tomdale says, I feel that it would have been much better to start with Ember CLI immediately. I can't see a good reason why we wouldn't, now that we know what it is. And I guess that was the point of my original questions: it was hard for me to figure out what Ember CLI was and how it was different to Ember.js, and most of the general help/community stuff available led me away from Ember CLI. (I like to learn by hacking examples, and a key way of accessing examples is through e.g. fiddles ... where you don't find much Ember CLI.) Across our team there was a significant waste of time ($$) due to not starting with Ember CLI straight away.

@harbulot, it seems to me (and I may be wrong) that the crux of the issue you raise is whether non-Ember stuff should even be migrated (or bolted on) to Ember (CLI or not) at all, as opposed to writing a complete app from scratch in Ember (CLI). And, to clarify, I have no ambitions of tackling that chestnut, and especially not in this github issue!

[ianwdunlop]

I liked how you could build a single page app with a few templates inside script tags and a bit of JS to demonstrate the power of ember. I hope it doesn't lose that. Deploying it in apache with, for example, a Rails backend was then a fairly simple step. I can understand the philosophy behind CLI but it feels a lot more cumbersome than what we have had up until now. It feels like I have to learn it all over again.

[harbulot]

whether non-Ember stuff should even be migrated (or bolted on) to Ember (CLI or not) at all, as opposed to writing a complete app from scratch in Ember (CLI)

Actually, it's step further than that: it's more about having a way, as a potential Ember user, to evaluate whether or not Ember can work in the context of your project.

Used as a script, you can try it progressively, without necessarily wasting too much time (provided the non-CLI approach is documented). For example, you can set aside short period of time for someone in the team to experiment with how a particular new feature or requirement could be implemented with Ember. An initial quick prototype side-project is manageable this way.

Used with CLI, you also have to worry about how to try Ember at all, before you've even started learning Ember itself. That's a bigger unknown in terms of project management.
With CLI, you may simply have to make major changes to your overall build and deployment mechanism, with potential unforeseen consequences. Before you can even try to evaluate whether or not Ember is right for you, you just have to invest some effort getting ready to try it, with a big question mark on the amount of time required.

(Note that this problem isn't limited to existing projects: it's quite conceivable that a project started now with Ember CLI evolves in such a way that it requires some integration with another framework or library that doesn't play well with Ember CLI in a few months. Of course, such problems could be linked with Ember itself (CLI or not), but by almost forcing CLI, there's an additional risk that needs to be managed.)

If you look over the past few years at the popularity of jQuery, which is usable with almost any server-side platform or framework, that popularity is in part due to the low barrier to adoption.
Mixing new jQuery code with existing JavaScript code or new non-jQuery code later is generally manageable. Integration and evolution can be handled progressively. That would be something much harder to do with Ember if Ember CLI is more or less mandatory (on top of the learning curve Ember already has).

I'm not saying Ember CLI is a bad thing, I'm just saying that the plain Ember script approach is also a major asset to the project, and that it should be equally documented.
Navigating the Ember documentation and trying to find out whether whatever we find (from blogs, Stack Overflow, ...) applies to the version we're using can be confusing as it is.
The prospect of not being able to find up-to-date documentation for the non-CLI approach makes the CLI approach more or less mandatory. Then, adopting Ember sound like an even bigger risk. Splitting the documentations just makes it likely that some parts will lag behind, or never be updated at all.

[harbulot]

I happen to think we can do a good job at both, but greenfield/Ember CLI will continue to be the focus of the happy path since that's where the growth potential is. After all, there are infinite number of apps to be written in the future, and a finite number of existing apps that will be ported. ;)

@tomdale I understand why the greenfield approach feels good and more appealing, but you seem to be making the assumption that the apps to be written in the future (a) will not have to be constrained by anything else developed in the past and (b) will rely on future requirements and external components that all play well with Ember CLI's constraints.
My guess is that it's unlikely to be the case ;-)