blog

AngularJS Best Practices: I’ve Been Doing It Wrong! Part 1 of 3

by

Angular JS logo

Three sanity-preserving ideas that will make me and you 10x more productive with real-world AngularJS applications.
This is the first in a three-part series on practical large-scale development with AngularJS. The TL;DR version is at the end of the article.
Coding Horrors Logo. © 1993 Steven C. McConnell
I’ve been working on a large webapp that uses AngularJS for a few months now. As many developers who pick up new things as they go do, I started with the tutorial (in the state it was a few month ago), adapted the parts of its code I understood into the app, and grew it from there, gradually adding and changing the code, which over time became harder and harder to manage. Now we’re dealing with JavaScript modules that span thousands of lines of code, contain huge controller functions, and in a few places, use such shortcuts for jQuery-Angular interaction that I would not want my grandma to accidentally find on my computer.
But it does not have to be that way. There are pragmatic, practical, achievable ways to maintain our AngularJS projects in a healthy state. All it takes is a little forethought, a bit of discipline and a general preference for sanity rather than madness.
So, this post is sort of a note to myself, but I’ll be glad if it helps anybody else to keep their Angular projects from turning into a mess. If you are seeing too much functionality lumped together into huge modules “for historical reasons”, or struggling through a 1,000-line procedure that manipulates DOM, updates models, and talks to the server at the same time, you know you’ve been doing it wrong, and your code needs restructuring.
Here are the three areas where I’m improving my AngularJS development, with the aid of the latest and greatest tools:

  • Project layout: it’s important how you structure your directories. You are adding a new feature, and you immediately know where its directives, controllers, and models go. You need to fix a bug in a feature you have not touched in a year, and you know exactly where to look.
  • Automatic testing: With Angular, as it turns out, testing is much more enjoyable than it used to be. If you’ve strayed from the righteous path of unit-testing your code (like I did), Angular makes it easy to straighten your ways and get into healthy habits of TDD again.
  • Avoiding bad habits and common mistakes, and taking advantage of the best tools and practices that have been developed by people much smarter than I: more on this later.

Part 1: Directory Layout that Scales with the Project

We need a directory structure that will make it easy to

  • add things as we go,
  • keep the size of our modules manageable,
  • and keep everything in an easy-to-navigate, logical structure.

Here’s one example of a proposed structure: angular-seed project. It is made by the AngularJS team, it includes lots of good things like tests and places for all the essential parts:

  • app/ – all of the files to be used in production
    • css/ – css files
    • img/ – image files
    • index.html – app layout file (the main html template file of the app)
    • js/ – javascript files
      • app.js – application
      • controllers.js – application controllers
      • directives.js – application directives
      • filters.js – custom angular filters
      • services.js – custom angular services
    • lib/ – angular and 3rd party javascript libraries
    • partials/ – angular view partials (partial html templates)
  • config/ – config files for running unit tests with Testacular/Karma
  • scripts/ – handy shell/js/ruby scripts (run unit tests and dev server)
  • test/ – test source files and libraries

However, as your project grows, you’ll add tons and tons of code into controllers, services and directives. Using a file for each of these areas steers you into a direction where you’ll end up with “piles on the floor” – you know your AccountListController is somewhere in the Controllers pile, but it will take you a while to find it. In other words, angular-seed packages your code by layers. Here’s a place for all controllers, here’s a place for data services, etc.
You can make it more usable by using sub-directories for controllers, and so on:

  • controllers/
    • LoginController.js
    • RegistrationController.js
    • AccountListController.js
    • SearchResultsController.js
  • directives.js
  • filters.js
  • services/
    • CartService.js
    • UserService.js
    • AccountService.js

This is much better, since you have a nice place for everything. Now I can easily find where to add new modules or where to find current code that handles Account Lists.
But what if I need to reuse my login controller in another application? I can just copy LoginController.js into the other app’s controllers directory. As soon as I do that and refresh the browser, I see an error: the system does not know what a User object is. Ah yes, I forgot to copy UserService.js into services directory. A more complex feature would also involve some custom directives and filters. And do not forget the tests! It would suck if I copied all that code into another project but forgot to copy its tests from all the subdirectories of tests/unit that correspond to controllers, services, filters and directives of this feature. So many places to remember to look into when reusing code! Yuck! My head hurts already.
Let’s try a different approach. Enter ng-boilerplate, the best AngularJS project template in the world (to my knowledge at the time of this writing). Here’s its version of module layout:

  • build/
  • src/
    • app/
    • assets/
    • components/
    • less/
  • testacular/ (or karma/)
  • vendor/
  • Grunfile.js
  • module.prefix
  • module.suffix
  • package.json

There’s a lot of stuff here, but that’s justifiable: we are talking about huge application scalability, not an introduction-level tutorial. I’ll focus on the main part, our application source, first, and then I’ll go through the essential supporting parts one by one.

Layout of src: feature-based modularization

  • src/
    • app/
      • about/
        • about.js
        • about.tpl.html
      • home/
        • home.js
        • home.less
        • home.spec.js
        • home.tpl.html
      • app.js
      • app.spec.js
    • assets/
    • components/
    • less/
    • index.html

Application-specific code lives under app/. In the boilerplate, the application has two sections, “home” and “about”. Each of the features has its own single directory, which contains everything: Angular module declaration, controllers, routes, templates, styles, and unit tests.
In a larger app, we’ll add more sub-directories for specific controllers, services and directives related to specific features. We’ll probably grow the test suite and place tests into a “tests” directory. But still, all will be contained in one place, so you know where to look for bugs related to the “home” feature, or to add more functionality to it. A feature can be copied for reuse in one operation. This will scale much better than the previous layer-based modularization. The best part of this layout is that any new developer who looks at your code will instantly understand what your application does. And you, looking at your own app a year from now, will not scratch your head and mumble obscenities about the moron who wrote this crap.
The .spec.js files are the unit tests. The build system will scan the directory structure and pick up all the tests automatically.
The .tpl.html files are HTML templates. The rest is not hard to follow if you peek into the source.
Note, again, the app-specific unit tests alongside app.js module. This is logical. This is good. I like it.
Assets contains static files – fonts, images, static style sheets (ng-boilerplate will place here an IE-specific stylesheet to enable Font Awesome for it).
Components is a place for reusable parts of the app – both third party and your own. Every component you place here should be drag-and-drop reusable in any other project; they should depend on no other components that aren’t similarly drag-and-drop reusable.
Less contains all the LESS/CSS sources. If you prefer SASS to LESS, you can replace it and use grunt-sass task to integrate SASS compilation into the Grunt build.
Finally, index.html is the page of our single-page application. In addition to being an HTML5 document and an AngularJS template, it is also a Grunt template (see the following section for details on Grunt), and variables defined in the Gruntfile.js, such as directory names based on the projec name can be used here.
Next, let’s look in more detail at all the other parts that make ng-boilerplate not just a though-through directory layout, but a real kickstarter for projects.

Grunt

Ng-boilerplate uses Grunt, “The JavaScript Task Runner” as its build system. Grunt automates gathering all assets for distribution, compiling LESS into CSS, linting and minifying JavaScript sources, maintaining the right paths in templates, and running unit tests. It also knows not to include unit tests into production package, and to combine all your JavaScript code into a single file. All these things happen automatically when Grunt is watching your project directory. This is pretty awesome.
Configuration for Grunt is in Gruntfile.js, and custom scripts for it are in build/ directory.
An important advantage that an automatic build system and automatic test suite gives is the ability to build on Travis-CI. The code is automatically tested on multiple browsers as soon as it is pushed to github. If you are working on an open-source project, it’s a sin not to take advantage of this.

Testacular (or Karma)

The creators of AngularJS made their own, truly spectacular, system for running unit tests. I’ll talk about unit tests in more details a bit later. For now, I’ll just say that this is what testacular/ (or karma/) directory is for: test configuration.

Vendor

The vendor/ folder contains libraries that are either foundational or necessary for the build processes to succeed. There is no automatic processing of anything in this directory during build process – if you wish to add a new library, you must add whatever logic is necessary to the Grunt build file. The documentation for this section contains an example of how to add jQuery to the vendor files.

Goodies: Bootstrap, Fonts, LESS

As a front-end developer, you are probably already familiar with these tools. We already use them in most projects – why not save time by making them part of the project template?
In the next part of the series, I’ll talk about automated testing with AngularJS, using the ng-boilerplate project template.

TL;DR (but really, read the whole three articles – it’s worth it)

  • Use ng-boilerplate as a template for your projects.
  • Learn to use unit-testing and end-to-end testing with Angular, and make it your religion. Use testacular/karma and Jasmine. It will save you months and years of development. Use end-to-end tests in addition to unit tests. Borrow test practices from good AngularJS applications.
  • Acquire new Angular habits, and avoid old habits that do not translate into AngularJS world.

Also see: AngularJS for jQuery Developers, I’ve Been Doing It Wrong (part 2)

+ more