// I need to

ModernizeUpgrade without breaking it RescueFix what someone else started Build NewTurn an idea into a product Reach More PeopleGet found, get used, include everyone

// Company

Case StudiesExpertiseAbout + CareersResourcesContact Book a call →
≡articleBuild New

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

AngularJS best practices, Part 1: lessons from a large webapp that outgrew the tutorial, and how to structure a big AngularJS project.

Art+Logic May 2, 20138 min read

From the Art+Logic archive · written in 2013. The tools may have moved on; the thinking still holds.

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:

Part 1: Directory Layout that Scales with the Project

We need a directory structure that will make it easy to

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:

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:

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:

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

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)

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

keep going

More to explore in Build New.

All Build New resources →
let's talk

Got a problem like this one?

Tell us what's stuck. A real person replies within one business day.

Talk to our team →

Talk to people who know software, not a sales script.

Your first call is with Aja, our VP of Sales. He'll help make sure you're solving the right problem. Here's what you'll cover together:

  1. What you're trying to accomplish

    The business goal first, then the technology.

  2. Possible approaches

    And the tradeoffs of each, in plain language.

  3. Risks you may not have considered

    Technical and business, before they cost you.

  4. Whether AI changes the math

    What's practical, and what's just hype for your project.

  5. Sensible next steps

    Even if the right next step is not us.

book-a-call.ics

Loading the scheduler…

Open the booking page →

Some problems are easier to explain in writing. Send us a few lines about what you're working on, and we'll reply within one business day. Helpful to include:

  1. What the software does, or should do
  2. What's stuck, or what's worrying you
  3. Any deadline or budget you have in mind
note.md

Loading the form…