📚 Community-driven set of best practices for AngularJS application development
The goal of this style guide is to present a set of best practices and style guidelines for one AngularJS application. These best practices are collected from:
Note 1: this is still a draft of the style guide, its main goal is to be community-driven so filling the gaps will be greatly appreciated by the whole community.
Note 2: before following any of the guidelines in the translations of the English document, make sure they are up-to date. The latest version of the AngularJS style guide is in the current document.
In this style guide you won't find common guidelines for JavaScript development. Such can be found at:
For AngularJS development recommended is the Google's JavaScript style guide.
In AngularJS's GitHub wiki there is a similar section by ProLoser, you can check it here.
Since a large AngularJS application has many components it's best to structure it in a directory hierarchy. There are two main approaches:
In this way the directory structure will look like:
. ├── app │ ├── app.js │ ├── controllers │ │ ├── home │ │ │ ├── FirstCtrl.js │ │ │ └── FirstCtrl.spec.js │ │ │ └── SecondCtrl.js │ │ │ └── SecondCtrl.spec.js │ │ └── about │ │ └── ThirdCtrl.js │ │ └── ThirdCtrl.spec.js │ ├── directives │ │ ├── home │ │ │ └── directive1.js │ │ │ └── directive1.spec.js │ │ └── about │ │ ├── directive2.js │ │ ├── directive2.spec.js │ │ └── directive3.js │ │ └── directive3.spec.js │ ├── filters │ │ ├── home │ │ └── about │ └── services │ ├── CommonService.js │ ├── CommonService.spec.js │ ├── cache │ │ ├── Cache1.js │ │ ├── Cache1.spec.js │ │ └── Cache2.js │ │ └── Cache2.spec.js │ └── models │ ├── Model1.spec.js │ ├── Model1.js │ └── Model2.spec.js │ └── Model2.js ├── partials ├── lib └── e2e-tests
Here is its layout:
. ├── app │ ├── app.js │ ├── common │ │ ├── controllers │ │ ├── directives │ │ ├── filters │ │ └── services │ ├── home │ │ ├── controllers │ │ │ ├── FirstCtrl.js │ │ │ ├── FirstCtrl.spec.js │ │ │ └── SecondCtrl.js │ │ │ └── SecondCtrl.spec.js │ │ ├── directives │ │ │ └── directive1.js │ │ │ └── directive1.spec.js │ │ ├── filters │ │ │ ├── filter1.js │ │ │ ├── filter1.spec.js │ │ │ └── filter2.js │ │ │ └── filter2.spec.js │ │ └── services │ │ ├── service1.js │ │ ├── service1.spec.js │ │ └── service2.js │ │ └── service2.spec.js │ └── about │ ├── controllers │ │ └── ThirdCtrl.js │ │ └── ThirdCtrl.spec.js │ ├── directives │ │ ├── directive2.js │ │ ├── directive2.spec.js │ │ └── directive3.js │ │ └── directive3.spec.js │ ├── filters │ │ └── filter3.js │ │ └── filter3.spec.js │ └── services │ └── service3.js │ └── service3.spec.js ├── partials ├── lib └── e2e-tests
app ├── app.js └── my-complex-module ├── controllers ├── directives ├── filters └── services
app └── directives ├── directive1 │ ├── directive1.html │ ├── directive1.js │ ├── directive1.spec.js │ └── directive1.sass └── directive2 ├── directive2.html ├── directive2.js ├── directive2.spec.js └── directive2.sass
This approach can be combined with both directory structures above. * The unit tests for a given component (
*.spec.js) should be located in the directory where the component is. This way when you make changes to a given component finding its test is easy. The tests also act as documentation and show use cases.
services ├── cache │ ├── cache1.js │ └── cache1.spec.js └── models ├── model1.js └── model1.spec.js
app.jsfile should contain route definitions, configuration and/or manual bootstrap (if required).
Conventions about component naming can be found in each component section.
TLDR; Put the scripts at the bottom.
MyApp
Keep things simple and put AngularJS specific directives after standard attributes. This will make it easier to skim your code and will make it easier to maintain because your attributes are consistently grouped and positioned.
Other HTML attributes should follow the Code Guide's recommendation
The following table is shown the naming conventions for every element:
Element |
Naming style | Example | usage |
---|---|---|---|
Modules | lowerCamelCase | angularApp | |
Controllers | Functionality + 'Ctrl' | AdminCtrl | |
Directives | lowerCamelCase | userInfo | |
Filters | lowerCamelCase | userFilter | |
Services | UpperCamelCase | User | constructor |
Factories | lowerCamelCase | dataFactory | others |
$timeoutinstead of
setTimeout
$intervalinstead of
setInterval
$windowinstead of
window
$documentinstead of
document
$httpinstead of
$.ajax
$locationinstead of
window.locationor
$window.location
$cookiesinstead of
document.cookie
This will make your testing easier and in some cases prevent unexpected behaviour (for example, if you missed
$scope.$applyin
setTimeout).
Automate your workflow using tools like:
Use promises (
$q) instead of callbacks. It will make your code look more elegant and clean, and save you from callback hell.
Use
$resourceinstead of
$httpwhen possible. The higher level of abstraction will save you from redundancy.
Use an AngularJS pre-minifier (ng-annotate) for preventing problems after minification.
Don't use globals. Resolve all dependencies using Dependency Injection, this will prevent bugs and monkey patching when testing.
Avoid globals by using Grunt/Gulp to wrap your code in Immediately Invoked Function Expression (IIFE). You can use plugins like grunt-wrap or gulp-wrap for this purpose. Example (using Gulp)
gulp.src("./src/*.js") .pipe(wrap('(function(){\n"use strict";\n\n})();')) .pipe(gulp.dest("./dist"));
Do not pollute your
$scope. Only add functions and variables that are being used in the templates.
Prefer the usage of controllers instead of
ngInit. There are only a few appropriate uses of ngInit, such as for aliasing special properties of ngRepeat, and for injecting data via server side scripting. Besides these few cases, you should use controllers rather than ngInit to initialize values on a scope. The expression passed to
ngInitshould go through lexing, parsing and evaluation by the Angular interpreter implemented inside the
$parseservice. This leads to:
$parseservice doesn't make a lot of sense in most cases, since
ngInitexpressions are often evaluated only once
Do not use
$prefix for the names of variables, properties and methods. This prefix is reserved for AngularJS usage.
Do not use
JQUERYinside your app, If you must, use
JQLiteinstead with
angular.element.
When resolving dependencies through the DI mechanism of AngularJS, sort the dependencies by their type - the built-in AngularJS dependencies should be first, followed by your custom ones:
module.factory('Service', function ($rootScope, $timeout, MyCustomDependency1, MyCustomDependency2) { return { //Something }; });
Modules should be named with lowerCamelCase. For indicating that module
bis submodule of module
ayou can nest them by using namespacing like:
a.b.
There are two common ways for structuring the modules:
0. By functionality 0. By component typeCurrently there's not a big difference, but the first way looks cleaner. Also, if lazy-loading modules is implemented (currently not in the AngularJS roadmap), it will improve the app's performance.
Ctrlin the end.
HomePageCtrl,
ShoppingCartCtrl,
AdminPanelCtrl, etc.).
function MyCtrl(dependency1, dependency2, ..., dependencyn) { // ... } module.controller('MyCtrl', MyCtrl);
In order to prevent problems with minification, you can automatically generate the array definition syntax from the standard one using tools like ng-annotate (and grunt task grunt-ng-annotate).
Another alternative will be to use
$injectlike:
angular .module('app') .controller('HomepageCtrl', HomepageCtrl);HomepageCtrl.$inject = ['$log', '$http', 'ngRoute'];
function HomepageCtrl($log, $http, ngRoute) { // ... }
Avoid use of
$scopeservice to define functions and properties as part of controllers. Use
$scopeonly if It's really needed:
$scope.$emit,
$scope.$broadcast, and
$scope.$on.
$scope.$watch,
$scope.$watchCollection
Prefer using
controller assyntax and capture
thisusing a variable:
{{ main.things }}
app.controller('MainCtrl', MainCtrl); MainCtrl.$inject = ['$http'];function MainCtrl ($http) { var vm = this; //a clearer visual connection on how is defined on the view vm.title = 'Some title'; vm.description = 'Some description';
$http.get('/api/main/things').then(function (response) { vm.things = response.data.things; // Adding 'things' as a property of the controller });
}
Avoid using
thiskeyword repeatedly inside a controller:
app.controller('MainCtrl', MainCtrl); MainCtrl.$inject = ['$http'];// Avoid function MainCtrl ($http) { this.title = 'Some title'; this.description = 'Some description'; $http.get('/api/main/things').then(function (response) { // Warning! 'this' is in a different context here. // The property will not be added as part of the controller context this.things = response.data.things; }); } ```
Using a consistent and short variable name is preferred, for example
vm
.The main benefits of using this syntax:
Creates an 'isolated' component - binded properties are not part of $scope
prototype chain. This is good practice since $scope
prototype inheritance has some major drawbacks (this is probably the reason it was removed on Angular 2):
Removes the use of $scope
when no need for special operations (as mentioned above). This is a good preparation for AngularJS V2.
Syntax is closer to that of a 'vanilla' JavaScript constructor
Digging more into controller as
: digging-into-angulars-controller-as-syntax
If using array definition syntax, use the original names of the controller's dependencies. This will help you produce more readable code:
function MyCtrl(l, h) {
// ...
}
module.controller('MyCtrl', ['$log', '$http', MyCtrl]);
</pre>
<p>which is less readable than:</p>
<pre class="language-JavaScript"> function MyCtrl($log, $http) {
// ...
}
module.controller('MyCtrl', ['$log', '$http', MyCtrl]);
</pre>
<p>This especially applies to a file that has so much code that you'd need to scroll through. This would possibly cause you to forget which variable is tied to which dependency.</p>
model, using a service. For example:
//This is a common behaviour (bad example) of using business logic inside a controller. angular.module('Store', []) .controller('OrderCtrl', function () { var vm = this;vm.items = []; vm.addToOrder = function (item) { vm.items.push(item);//-->Business logic inside controller }; vm.removeFromOrder = function (item) { vm.items.splice(vm.items.indexOf(item), 1);//-->Business logic inside controller }; vm.totalPrice = function () { return vm.items.reduce(function (memo, item) { return memo + (item.qty * item.price);//-->Business logic inside controller }, 0); };
});
When delegating business logic into a 'model' service, controller will look like this (see 'use services as your Model' for service-model implementation):
// order is used as a 'model' angular.module('Store', []) .controller('OrderCtrl', function (order) { var vm = this;vm.items = order.items; vm.addToOrder = function (item) { order.addToOrder(item); }; vm.removeFromOrder = function (item) { order.removeFromOrder(item); }; vm.totalPrice = function () { return order.total(); };
});
Why business logic / app state inside controllers is bad? * Controllers instantiated for each view and dies when the view unloads * Controllers are not reusable - they are coupled with the view * Controllers are not meant to be injected
$emit,
$broadcastand
$onmethods. The emitted and broadcasted messages should be kept to a minimum.
$emit,
$broadcastand manage it carefully because of name collisions and possible bugs.
Example:
// app.js /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Custom events: - 'authorization-message' - description of the message - { user, role, action } - data format - user - a string, which contains the username - role - an ID of the role the user has - action - specific action the user tries to perform * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
function myFormat() { return function () { // ... }; } module.filter('myFormat', myFormat);function MyCtrl($scope, myFormatFilter) { // ... }
module.controller('MyCtrl', MyCtrl);
controllerAssyntax):
app.js
javascript module.config(function ($routeProvider) { $routeProvider .when('/route', { templateUrl: 'partials/template.html', controller: 'HomeCtrl', controllerAs: 'home' }); });HomeCtrl ```javascript function HomeCtrl() { var vm = this;
vm.bindingValue = 42;
}
**template.html**html ```
scopeinstead of
$scopein your link function. In the compile, post/pre link functions you have already defined arguments which will be passed when the function is invoked, you won't be able to change them using DI. This style is also used in AngularJS's source code.
ngor
uiprefixes since they are reserved for AngularJS and AngularJS UI usage.
scope.$on('$destroy', fn)for cleaning up. This is especially useful when you're wrapping third-party plugins as directives.
$scewhen you should deal with untrusted content.
$digestloop so creating a slow filter will slow down your app.
This section includes information about the service component in AngularJS. It is not dependent of the way of definition (i.e. as provider,
.factory,
.service), except if explicitly mentioned.
Use camelCase to name your services.
function MainCtrl(User) { var vm = this; vm.user = new User('foo', 42); }module.controller('MainCtrl', MainCtrl);
function User(name, age) { this.name = name; this.age = age; }
module.factory('User', function () { return User; });
Encapsulate all the business logic in services. Prefer using it as your
model. For example: ```Javascript // order is the 'model' angular.module('Store') .factory('order', function () { var add = function (item) { this.items.push (item); };
var remove = function (item) { if (this.items.indexOf(item) > -1) { this.items.splice(this.items.indexOf(item), 1); } };
var total = function () { return this.items.reduce(function (memo, item) { return memo + (item.qty * item.price); }, 0); };
return { items: [], addToOrder: add, removeFromOrder: remove, totalPrice: total }; }); ```
See 'Avoid writing business logic inside controllers' for an example of a controller consuming this service. * Services representing the domain preferably a
serviceinstead of a
factory. In this way we can take advantage of the "klassical" inheritance easier:
```JavaScript function Human() { //body } Human.prototype.talk = function () { return "I'm talking"; };function Developer() { //body } Developer.prototype = Object.create(Human.prototype); Developer.prototype.code = function () { return "I'm coding"; };
myModule.service('human', Human); myModule.service('developer', Developer);
```
$cacheFactory. This should be used to cache results from requests or heavy computations.
If given service requires configuration define the service as provider and configure it in the
configcallback like:
angular.module('demo', []) .config(function ($provide) { $provide.provider('sample', function () { var foo = 42; return { setFoo: function (f) { foo = f; }, $get: function () { return { foo: foo }; } }; }); });var demo = angular.module('demo');
demo.config(function (sampleProvider) { sampleProvider.setFoo(41); });
ng-bindor
ng-cloakinstead of simple
{{ }}to prevent flashing content.
srcof an image dynamically use
ng-srcinstead of
srcwith
{{ }}template.
hrefof an anchor tag dynamically use
ng-hrefinstead of
hrefwith
{{ }}template.
styleattribute with
{{ }}, use the directive
ng-stylewith object-like parameters and scope variables as values:
my beautifully styled div which will work in IE;
angular .module('app') .controller('MainCtrl', MainCtrl);MainCtrl.$inject = [];
function MainCtrl() { var vm = this; vm.divStyle = { width: 200, position: 'relative' }; }
resolveto resolve dependencies before the view is shown.
resolvecallback. Isolate all the requests inside appropriate services. This way you can enable caching and follow the separation of concerns principle.
E2E tests are the next common sense step after unit tests, that will allow you to trace bugs and errors in the behaviour of your system. They are great for providing a sanity check that most common scenarios of using your application works. This way you can automate the process and run it each time before you deploy your application.
Ideally, Angular End-to-End tests are written in Jasmine. These tests are run using the Protractor E2E test runner which uses native events and has special features for Angular applications.
File structure:
. ├── app │ ├── app.js │ ├── home │ │ ├── home.html │ │ ├── controllers │ │ │ ├── FirstCtrl.js │ │ │ ├── FirstCtrl.spec.js │ │ ├── directives │ │ │ └── directive1.js │ │ │ └── directive1.spec.js │ │ ├── filters │ │ │ ├── filter1.js │ │ │ └── filter1.spec.js │ │ └── services │ │ ├── service1.js │ │ └── service1.spec.js │ └── about │ ├── about.html │ ├── controllers │ │ └── ThirdCtrl.js │ │ └── ThirdCtrl.spec.js │ └── directives │ ├── directive2.js │ └── directive2.spec.js ├── partials ├── lib └── e2e-tests ├── protractor.conf.js └── specs ├── home.js └── about.js
angular-translate.
Optimize the digest cycle
$digestloop explicitly (it should happen only in exceptional cases), invoke it only when required (for example: when using real-time communication, don't cause a
$digestloop in each received message).
bindoncefor older versions of AngularJS or one-time bindings in AngularJS >=1.3.0.
htmlor{{ ::main.things }}
htmlAfter that, no watchers will be created for
main.thingsand any changes of
main.thingswill not update the view.
$watchas simple as possible. Making heavy and slow computations in a single
$watchwill slow down the whole application (the
$digestloop is done in a single thread because of the single-threaded nature of JavaScript).
$watchCollection, which performs a shallow check for equality of the result of the watched expression and the previous value of the expression's evaluation.
$timeoutfunction to false to skip the
$digestloop when no watched variables are impacted by the invocation of the
$timeoutcallback function.
Consider decreasing number of network requests by bundling/caching html template files into your main javascript file, using grunt-html2js / gulp-html2js. See here and here for details. This is particularly useful when the project has a lot of small html templates that can be a part of the main (minified and gzipped) javascript file.
Since the goal of this style guide is to be community-driven, contributions are greatly appreciated. For example, you can contribute by extending the Testing section or by translating the style guide to your language.
mgechev | morizotter | chatii2412 | pascalockert | yanivefraim | ericguirbal |
agnislav | ray7551 | mainyaa | LeonardCModoran | elfinxx | tiagobarreto |
Xuefeng-Zhu | SullyP | giacomocusinato | rubystream | lukaszklis | Spuffynism |
susieyy | cironunes | cavarzan | guiltry | MSafter | mingchen |
jmblog | luixaviles | andreasonny83 | kuzzmi | jabhishek | adambabik |
astalker | clbn | atodorov | apetro | valgreens | bitdeli-chef |
meetbryce | unseen1980 | cminhho | dwmkerr | kuzmeig1 | dominickolbe |
gsamokovarov | grvcoelho | yassirh | bargaorobalo | hermankan | jesselpalmer |
capaj | johnnyghost | jordanyee | whoan | nacyot | mariolamacchia |
mischkl | michaelmov | kirstein | mo-gr | mortonfox | cryptojuice |
nktssh | olafahn | olov | vorktanamobay | QuietHeartThinkingFar | raphaelfruneaux |
sahat | ganchiku | kaneshin | imaimiami | dooart | thomastuts |
UrielMiranda | vkarampinis | grapswiz | coderhaoxin | giantray | ntaoo |
seyyah | dchest |