Angular-sprout: The scalable angular seed app

The angular-seed app is a wonderful way to hit the ground running with AngularJS. Unfortunately, it doesn’t scale particularly well and its sparse implementation leaves new devs with too many questions about building real world applications using the angular framework. angular-sprout has been created to address these issues.
angular-sprout starts with the assumption that a decent real world seed app must possess the following traits. It must:

  • be opinionated
  • be scalable
  • be just light enough

angular-sprout is very opinionated. One of the first things we do is throw away the angular-seed notion of javascript packages as represented by the services.js, controller.js, etc. Instead, angular-sprout insists that we break modules into their own files and organize them by feature and not module type. It is important that we treat everything as an encapsulated feature, even the application bootstrap module. This choice empowers developers to work on features with all the logical components living in the same directory. This structure also has obvious benefits for multiple developers wishing to avoid working within the same units of code. Additionally, the angular-sprout app strives to keep devs sane by limiting an app to 3 levels of hierarchy. Too much directory depth makes it difficult to decide where new code should go.

The angular-sprout directory structure

    app/                                    
application/
application.css
application.js
configuration-service.js
date-time/
to-datetime-string.css
details/
details-controller.js
details-partial.js
error/
error-controller.js
error-partial.js
menu/
menu-controller.js
menu-partial.js
menu-service.js
menu-item-directive.js
menu-item-template.html
items.json
index.html
lib/
angular.js
angular.min.js
angular-*.js

config/testacular.conf.js
config/testacular-e2e.conf.js

scripts/
e2e-test.sh
e2e-test.bat
test.bat
test.sh
web-server.js

e2e/
home-e2e.html
layout-e2e.js

angular-sprout is ready to scale. As illustrated above, modules are broken out into descriptive files and suffixed with -filter.js, -directive.js, -service.js, -controller.js for application modules, and -e2e.js or -unit.js for end to end and unit tests respectively. This is an easy pattern to implement and understand even after your app grows to hundreds of modules. The angular-sprout app also introduces javascript namespaces that are defined in the application.js. Each new module is added to a namespace that helps prevent global scope pollution and adds another layer of easily scalable organization.

Namespaces defined in application.js

var Application = Application || {};

Application.Controllers = Application.Controllers || {};

Application.Filters = angular.module('application.filters', []);
Application.Services = angular.module('application.services', []);
Application.Directives = angular.module('application.directives', []);

angular.module('application', ['application.filters', 'application.services', 'application.directives'])

angular-sprout is just light enough. While it’s important that a seed app remain out of the way, it is more important that the app give you the tools you need to get off the ground in a real world way. angular-sprout strives to give the developer a working “not to trivial” example of every major angular module type as well as real world testing examples that avoid poor practices like unit testing filters with e2e tests.

Check out https://github.com/thedigitalself/angular-sprout to get started.

JavaScript

javascript, angular-sprout, angularjs, angular-seed, angular

Published on October 16, 2012 by James Wanga.