The bumpy road to learning Ember.js

Wed Feb 18 2015 17:32:01 GMT+0000 (Greenwich Mean Time)

I'm doing some interoperability research lately and one of the things I'm investigating is Ember.js.

I had never used it before, but heard raving comments about it, so I guess I was expecting a smooth paved way lined with flowers and what not... and what I found was a lot of mental dissonances and mismatches between what I expected to find and what Ember wants me to do.

In the interests of reproducibility, this was my way of "learning Ember.js":

On Ember's website

I went to Ember's website and clicked on /about. It just highlights separate features but doesn't show me a complete one-page kind of quick start snippet. It also is pointing me to download a JS file which is weird to me as I might have got (badly used) to be able to npm install modern JS packages / libraries using npm.

To npm

So I opened npmjs.org in a new tab and searched for 'ember'. The results seem odd to me. The ember package seems to be legit, as it has Yehuda Katz as one of the maintainers, but it's at version 1.0.0-pre2 and was last published two years ago. Well, that doesn't seem very useful. It's probably missing functionalities compared to whatever the current documentation in their website mention, yet still people are downloading it: 1104 downloads last week, which might have got a bunch of them confused like me too. So...

... back to Ember's website

I go back to Ember's website, and click on Guides. Maybe I will find everything there!

I am greeted with a 30 minute screencast.

I am not sure if I can skip it without missing something essential--perhaps a note saying that it's OK to head straight to the "getting started" section would be nice. And users can always go back to it if they want.

In the end, I decided not to watch it, because as a non native English speaker I find videos where I can't see the speaker's lips really hard to follow---I'd rather just read text, as there's no risk of misunderstandings.

So I click on getting started on the left.

Getting started

The guide wants to show you how to rebuild TodoMVC. I am not interested in learning that, but I want to know how to get a basic Ember structure up and running, so I skim over the first two steps: Planning and Creating a mockup and jump to the third step titled Obtaining Ember and dependencies.

It enumerates dependencies and then tells me to add four script tags before the end of the body tag.

This is not even "sole fighting Ember's convention over configuration" yet---it's me thinking "this is 2015. I should be able to require() away instead of embedding script tags on a file, and what kind of manual dependency management is this?"

Searching away

Of course I won't accept defeat this easily. Someone must have figured this out already! This is not an obscure library that someone wrote in a basement, right? I search around using various combinations of terms:

npm ember
gulp ember
browserify ember
require ember
... and etc

The results of my searches are mostly fruitless--I only find half baked attempts that "work kind of OK" for the person that posted them, but seem really fragile according to commenters.

A compromise with gulp-bower

I don't know what it is in Ember's architecture that makes it not play nice with Browserify, but I don't want to fix it myself.

I keep reading and find this other section titled Getting Ember. It links to the builds section which is a page from where you can download JS files (not what I want) but it also says that you can install Ember with Bower.

It's not ideal, but it can be scripted, which makes it better than manually downloading JS files, so I decide to opt for an intermediate solution in which I will sort of cave in and use Bower, but via gulp, using gulp-bower.

Of course in order to use Bower you better know which dependencies and which versions of the dependencies to use, so you can build a bower.json file that Bower/gulp-bower can read to install packages.

Ember's website suggests using this:


{
    "name": "your-app",
    "dependencies": {
        "ember": "~1.6",
        "ember-data": "~1.0.0-beta.8"
    }
}

I believe this is outdated (Ember is at 1.10, the builds page say). I adjust it as best as I can and run my magic gulp-bower sorcery. The packages are downloaded as expected, and I can reference them in my html, with script tags.

But what to include...?

I start by adding bower_components/ember/ember.js. A message in the console invites me to include ember.debug.js instead, which I do. A bit after I find that I might indeed need jQuery (#sorrynotsorry for the pun). I also find that I need to include a template engine thanks to another error message. None of these were mentioned on the section that refers to using Bower.

I remember to go back to the Getting Started guide and look for the bunch of script tags that I need to include:


<script src="js/libs/jquery-1.11.2.min.js"></script>
<script src="js/libs/handlebars-v1.3.0.js"></script>
<script src="js/libs/ember.js"></script>
<script src="js/libs/ember-data.js"></script>

I manually add the missing libraries to bower.json, change the script tags to use the actual bower_components/ paths my app is using, guess which script file it actually to use, and hope for the best.

Finally...!

It works! I can finally follow the actual tutorials!

Which I do, yet even if I'm feeling weird that they invite you to stick things on the Window global object:


window.Todos = Ember.Application.create();

Later I get stuck on the Modeling data section. It mentions some DS object which I have no idea where it comes from--perhaps DataSomething? I don't know. The API page doesn't show any module starting with a D.

So I skip that and jump to playing with components and templates. I find how to do two way binding, which is nice, when it works, and it's good to find cases in which things do not work because that's the point of my research. I also see the potential in using the MVC archetype, and the API seems reasonably readable...

But at this point, I'm really tired.

All this going back and forth for satisfying the minimum requirements could have been solved from the start if Ember used a dependency manager.

People tell me in Twitter that Ember wants you to use ember-cli to solve all these issues. But I don't want to use their CLI: I like using my existing tools. Also, perhaps Twitter should not be the right place to learn about this. If Ember wants their users to use the CLI, it should probably be in the documentation.

In 2015, again, I assume that JS developers are good developer-citizens (developzens?), and will make it easy to compose different pieces together without interfering with other people's setups.

Yet Ember feels a bit like this weird assembly of pieces and techniques of years past, and that makes adopting it into your existing workflow way more complex than it should be.

Thanks

With thanks to Brittany Storoz for proofreading this post and making it way, way better than it would have been otherwise.