AngularJS Pain Points

I’ve been using AngularJS for almost 3 months. I had heard quite a lot about Angular before this time – many people were talking about it being the ‘next big thing’ and how it could become the defacto JavaScript framework for client-side development.

At first glance I was very impressed with Angular – the two-way binding removes the need for constantly updating the view and the scope objects makes for a clean separation between the controller and the view. There were other elements which were very appealing as well – a complete documentation site, a focus on testability, and a clean separation of concerns through built-in dependency injection. As I said, at first glance it definitely looks very impressive.

Now that I’m more familiar with AngularJS I am unfortunately less impressed. The framework is definitely powerful, but there are various factors which seem to make Angular more painful to work with than I thought would be the case. There are definitely some great features in the framework, but I definitely don’t think Angular is the clear winner in the JavaScript-framework-wars by any means.

The Documentation

I’ve spoken to other developers who use Angular and the common complaint is always about the documentation. The Angular documentation is incredibly thin – meaning it briefly covers every topic – and suffers from a lack of code examples. For example, one of the things I struggled with early on was to use the $httpBackend module in E2E testing. Sure enough, there is a page in the documentation and it explains how to setup the $httpBackend object to mock out certain responses. However, after the 14-line code snippet the documentation simply states:

Afterwards, bootstrap your app with this new module.

What the documentation conveniently ignores is that you can’t simply inject a mock httpBackend into your application since your application will then stop working when you’re not in test mode. So you need to figure out a way to load all the test dependencies and setup only in test mode while avoiding possible issues when you deploy your application. There is also an additional dependency on the angular-mocks script which you need to include. These kinds of omissions are very common and can very easily cause you to waste fruitless hours experimenting with different solutions to find the answer.

Of course, since Angular is an open source framework many enthusiasts will simply see this as a community problem – the source code is available for anyone to read – we can simply write the documentation ourselves. While I disagree with the sentiment, I find this even more difficult with Angular since the framework is very large and complicated. It takes a substantial effort from any developer to understand the source code to the extent where writing documentation is possible. For example, the uncompressed AngularJS core library is 14,846 lines of code. Compare this to the the uncompressed core library for SpineJS which is only 1174 lines! I would be the first to advocate that lines of code is a terrible measure of source code, but the numbers definitely indicate that Angular is a large framework which makes the lack of documentation very painful.

The other problem with the documentation is the incredible lack of any SEO (Search Engine Optimization) focus. I say incredible because I would expect a library created and maintained by Google developers to at least be decently optimized for search, while the exact opposite is true. The Angular documentation site is actually a very good example of how bad SEO can be. For example, this afternoon I couldn’t remember all the different matchers for E2E testing so I simply googled it.

AngularJS e2e testing matchers google search

The only link to the Angular documentation is to a tutorial link – the actual page that contains the matchers is nowhere to be seen. If you add ‘documentation’ to the search term you simply get the root of the documentation site.

The Testing

Angular supports two types of testing – Unit testing and E2E testing (end-to-end). The Unit testing uses Jasmine (which is great) and the E2E testing is part of the Angular framework.

Angular does go a long way towards making your code testable (and you can definitely TDD most of it), but there are some rather painful issues along the way. For one thing, the documentation doesn’t really offer much in the way of best practices (at the time of writing, the Unit testing documentation has 6 sections which are blank) which means you will probably spend quite some time figuring out how to properly create your controllers and inject mock objects where necessary.

Once you get over the initial learning curve you will need to contend with 2 frameworks which have very similar – yet different – syntax. The Unit testing framework uses the popular Jasmine matchers while the E2E framework uses it’s own set of matchers. The documentation describes it as Jasmine-like BDD syntax.

The Angular framework doesn’t have any sort of test runner built-in, although Karma is suggested. Unfortunately this is another pain point. For example, this is some example output from a test failure in my current project (obfuscated, of course).

PhantomJS 1.9 (Mac) Validations should return false when none of the subfields are filled in FAILED
        Expected true to be falsy.
PhantomJS 1.9 (Mac) Validations should return false when only month subfield is filled in FAILED
        Expected true to be falsy.

Unfortunately the runner doesn’t give us any indication which file the test belongs to, or which line number. This means you usually need to do some creative grep-ing to find the culprit. To avoid this issue we have started to use describe blocks with the name of the controller or service, which is less than ideal.

The Overall Complexity

Angular is definitely a very powerful framework. It’s very easy to create some very powerful interactions with a few simple include statements and relatively little JavaScript (or CoffeeScript). However, this power comes at the cost of high complexity.

I find the argument usually made by staunch Angular supporters is that it’s pretty much always less lines of code than another framework. While I agree with this statement I think it’s a rather poor measure of a framework. If we were to draw a graph of complexity versus power in different JavaScript frameworks, Angular would plot very high on the power axis, but also very high on the complexity axis. The power of Angular comes at a high cost.

On this hypothetical graph there should be a sweet spot – where the additional complexity is no longer worth the additional power a framework offers. In my opinion Angular is perhaps slightly too far along on this tradeoff. It’s no use to be able to code a page in half the amount of JavaScript if it takes a new developer 3 times as long to ramp up on that code.

The bottom line is that Angular has a steep learning curve. Don’t underestimate it, especially given the lack of documentation and best practices.

Angular is still great

After all this negativity you might think that I’m completely against Angular. Not in the least. I am merely pointing out the different pains you might experience if you’re working with Angular on a daily basis.

Angular is still a great framework – it has some great features and it’s really powerful. But I wouldn’t declare it the clear winner in the JavaScript wars just yet.

Angular is simply another option to choose from for your next JavaScript project. It might be the right choice for you. Might.

Happy coding.

Tags: AngularJS, JavaScript

  1. Bryan says:

    Great summary of the pain points you’ve experienced. I am starting a new project and have made the decision to use AngularJS as my client side MVVM platform. I would be interested to know which JS lib you think is the most mature in terms of modern features and completeness.

  2. Alessandro says:

    Couple of my personal thoughts on this article:

    * The Documentation: yeah, you’re right…the lack of very good documentation is a pity. Probably the worst problem in angular js.

    * Testing: I completely disagree with you here.
    karma-js IS the angular js test runner. It’s great and it reports everything you need to know. Angular team encourages a bdd approach so your spec should document the code and it should be straightforward to find which spec is failing (Why is describe blocks named after components a bad idea? You ARE describing it!). Btw, I get the line number error when I run it, probably we have different version or set-up.
    Moreover it’s the first MV* framework which really concentrate on testing (thanks mainly to DI), and it’s maybe the only part where the docs don’t completely suck: all examples in the site have the relative tests going with it…I really started enjoying tests thanks to angular.
    Last but not least, there are a lot of angularjs video which explain how to write tests, best practices and all this stuff!

    *Search Engine Optimization: it’s a SPA problem, not specific to any particular framework. A common solution is to use PhantomJS to generate pages on the server for crawlers use – anyway, which kind of tool did you expect?

    *The overall complexity: I agree with you – the learning curve of the framework IS steep indeed, but – in my opinion of course – it’s worth it. I’m not an angular master but each time I have to use something else…it just hurts.

    Concluding: I know, most of this discussion are just a matter of personal preference but indeed, some of your arguments doesn’t look too valid. Mixing very good points (like the lack of documentation) to to very poors one (like the testing capabilities) makes your article less authoritative – at least for me :)

  3. Aaron Smith says:

    It’s good to read that after using it for this long the biggest complaints are the things the Angular team has promised to fix with the 1.2 release which will come out any day now.

    Here’s some relevant points:

    * Karma will no longer be the e2e test solution for angular, protractor ( will be. I’ve been using it and it is flexible and smart. Best of all, it simply extends WebdriverJS, which uses a selenium server and is widely used in many, many languages.
    * Documentation will be overhauled in 1.2. I assume that having better docs will also help the search results issues and the unit testing issues you explained.

    One more note: high complexity leads to high flexibility in the case of Angular. Thanks to this, we can use Angular for our enterprise application and handle any situation we need to gracefully.

    Please watch this video: (Angular 1.2 and beyond) to get the full context.

  4. @Bryan: In terms of deciding on a JavaScript framework – there are so many, I would suggest you choose one based on your needs. I’m a big fan of SpineJS, but if you’re doing heavy filtering in the client (for example) there might be better libraries out there. I’m not saying Angular is a bad choice – by any means – I’m saying there are some tradeoffs when deciding if it’s the right library for your situation.

  5. @Alessandro: In terms of the testing, I never said testing in AngularJS is bad – in fact I think it’s pretty good. I’m merely pointing out that there are some painful issues with it. Perhaps I do have something wrong with my Karma setup, I was only commenting on my experience. I wouldn’t say it’s the only MV* framework that focuses on testing though – in fact, I would say most of the modern frameworks have some degree of focus on testability. DI doesn’t make your application more testable – DI is about separation of concerns. For example, Rails uses no DI and it’s still perfectly testable. I have used other JavaScript frameworks – I don’t want to mention others since I don’t want to make it seems like there is some perfect framework I’m advocating – where there is no DI but you can still test everything. The Angular videos on the testing is definitely helpful, I’m not disputing that. I was merely pointing out things which I found painful to work with in terms of testing.

    In terms of SEO, saying it’s because the documentation is a SPA is a really really poor reason. Why would you make it a SPA then at all? And as you rightly pointed out, you can do SEO even with a SPA. Again, I’m merely pointing out that it’s painful to work with. It’s not like every time I fail to find something on google I go ‘oh it’s ok because at least it’s a SPA’. Documentation sites should have some form of SEO, don’t you agree?

    Anyways, it sounds like you’re really enjoying Angular! :)

  6. @Aaron: Thanks for the link! Looking forward to Angular 1.2!

  7. Olivier Clément says:

    I have to say I’m with Alessandro here
    Some of your points are valid, like doc being scarce AND confusing mostly.

    But I think the rest of your points are mostly caused by lack of experience with the framework; I have been working on an Angular project for a bit over a year now, and I am still learning stuff everyday.

    I honestly think that in 3 months you cannot really assess this kind of framework (being complex and all) and have a good understanding of it’s ecosystem. Of course I am merely expressing an opinion here, and not all people learn at the same rate or have the same kind of background experience, but still, 3 months is pretty short for this sort of things I think

    If I may, I would like to point you the fact that the Angular community is incredibly active and helpful over on Google Groups, where even the core developers participate a lot on there. This presence, in my opinion, is solving the documentation problem by itself, and many others.

    Happy coding!

  8. George says:

    Here’s my concern. When I started with jQuery, everything was intuitive, and if it wasn’t, it was documented. Documentation is the single reason I can’t continue with Angular. Not that I won’t, but there simply isn’t enough information out there for me to go one with what I need to build. I wanted to do a simple ajax call, nothing. Then I read somewhere else that I might need another library, or include, or dependency…. that’s not good programming. It’s lazy programming at its finest. Too many dependencies make things complex and hard to fix when they break. This is something I’ve learned over my 11+ years of development. KISS (Keep it simple, stupid). Yes, there may be additional manual labor on my end, but that’s why it’s called work… duh! Trying to complicate things for others by making them simple for you only is just plain evil… Anyway, that’s my two cents. jQuery is the most popular library out there by far, and for very simple reasons… It’s simple and intuitive. That logic works for everything from iPhones to cars.

  9. George says:

    Example of simplicity. I read somewhere that to do an ajax call, I have to do this:

    $http.get(‘/items/list.json’).success(function (data) {

    When I ran it, nothing! Not even in the network panel. I did get an error however. Something about curly brackets. In jQuery, to do an ajax call, all you had to do was: $.ajax(), pass in your settings as JSON which we’re already familiar with since we’re developing in JS. And bam! Network panel http request sent out. Simple. Logical. Just made sense. When you try to change the way people think, they’ll simply just stop thinking. That’s counter-intuitiveness.

  10. Neil Moffatt says:

    Good article – but why after this long has Google not seen fit to do something about the thin and terse state of the documentation? I struggled to get things working in Angular via intuition as the syntax is frequently counter-intuitive. So good documentation is vital. Decided to write a beginners web site from the outside in – from what you might want to do on a web page to the tools and syntax that Angular offers you to do that. Almost all web sites simply focus on the syntax – until users know why they might want a directive or a service, that is putting the cart before the horse. I have also sought to collate together the thinly spread syntax of Angular html attributes. Would love feedback to see if I a on the right track.

  11. helloworlder says:

    I’ve been between a rock and a hard place deciding on whether to use AngularJS or not. So far in my research, it looks great for CRUD type applications where it’s mainly forms. However, when I started thinking about how to integrate complex GUI and other graphics components, and also possibly real time socket data as well as state management for all these things, I’m really struggling to make it fit into AngularJS without going crazy. It clearly’s no silver bullet but has its place among many other libraries and frameworks.

  12. @helloworlder AngularJS is definitely very good for CRUD applications – it just works really well for forms. You probably need to figure out the main feature of your app – if it’s CRUD, Angular would probably be a good fit. I always recommend that build something meaningful in the framework before making a decision.